From 2644dfd651721c7f00cc52c1365c5c988829c869 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 06:49:31 -0700
Subject: [PATCH 001/124] perf(agents): avoid duplicate tool catalog
 fingerprinting (#127188)

Co-authored-by: Amp <amp@ampcode.com>
---
 src/agents/tool-search-catalog.ts | 32 +++++++++++-----
 src/agents/tool-search.test.ts    | 64 +++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+), 10 deletions(-)

diff --git a/src/agents/tool-search-catalog.ts b/src/agents/tool-search-catalog.ts
index d461c960dfff..21cf57482ea7 100644
--- a/src/agents/tool-search-catalog.ts
+++ b/src/agents/tool-search-catalog.ts
@@ -274,6 +274,7 @@ function registerToolSearchCatalog(params: {
   catalogRef: ToolSearchCatalogRef;
   entries: ToolSearchCatalogEntry[];
   append?: boolean;
+  fingerprint?: string;
 }): ToolSearchCatalogSession {
   const prior = params.append ? params.catalogRef.current : undefined;
   const byId = new Map((prior?.entries ?? []).map((entry) => [entry.id, entry]));
@@ -289,7 +290,13 @@ function registerToolSearchCatalog(params: {
     describeCount: prior?.describeCount ?? 0,
     callCount: prior?.callCount ?? 0,
   };
-  catalogFingerprints.set(next, catalogEntriesFingerprint(next.entries));
+  // The supplied fingerprint describes the input entries. Duplicate IDs are
+  // last-write-wins, so recompute when registration changed the entry set.
+  const fingerprint =
+    params.fingerprint !== undefined && next.entries.length === params.entries.length
+      ? params.fingerprint
+      : catalogEntriesFingerprint(next.entries);
+  catalogFingerprints.set(next, fingerprint);
   params.catalogRef.current = next;
   params.catalogRef.onChange?.();
   return next;
@@ -437,8 +444,15 @@ export function applyToolCatalogCompaction(
     }
     visible.push(tool);
   }
-  const incomingFingerprint = catalogEntriesFingerprint(catalog);
+  // Hook-wrapped entries carry run context and have fresh executable identities, so
+  // their snapshots cannot be reused and would only retain the completed run.
+  const hasHookBoundEntry = catalog.some((entry) =>
+    isToolWrappedWithBeforeToolCallHook(entry.tool as AnyAgentTool),
+  );
+  const reusableKey = hasHookBoundEntry ? undefined : reusableCatalogKey(params);
   const existingCatalog = catalogRef.current;
+  const incomingFingerprint =
+    existingCatalog || reusableKey ? catalogEntriesFingerprint(catalog) : undefined;
   if (existingCatalog && catalogFingerprints.get(existingCatalog) === incomingFingerprint) {
     return {
       tools: visible,
@@ -449,14 +463,8 @@ export function applyToolCatalogCompaction(
     };
   }
 
-  // Hook-wrapped entries carry run context and have fresh executable identities, so
-  // their snapshots cannot be reused and would only retain the completed run.
-  const hasHookBoundEntry = catalog.some((entry) =>
-    isToolWrappedWithBeforeToolCallHook(entry.tool as AnyAgentTool),
-  );
-  const reusableKey = hasHookBoundEntry ? undefined : reusableCatalogKey(params);
   const reusableSnapshot = reusableKey ? reusableCatalogSnapshots.get(reusableKey) : undefined;
-  if (reusableSnapshot?.fingerprint === incomingFingerprint) {
+  if (reusableSnapshot && reusableSnapshot.fingerprint === incomingFingerprint) {
     restoreToolSearchCatalog({
       catalogRef,
       entries: reusableSnapshot.entries,
@@ -475,7 +483,11 @@ export function applyToolCatalogCompaction(
     };
   }
 
-  const registered = registerToolSearchCatalog({ catalogRef, entries: catalog });
+  const registered = registerToolSearchCatalog({
+    catalogRef,
+    entries: catalog,
+    fingerprint: incomingFingerprint,
+  });
   rememberReusableCatalog(reusableKey, registered);
   return {
     tools: visible,
diff --git a/src/agents/tool-search.test.ts b/src/agents/tool-search.test.ts
index 5949bbf9d821..1ebc8eb7d9ac 100644
--- a/src/agents/tool-search.test.ts
+++ b/src/agents/tool-search.test.ts
@@ -3677,6 +3677,70 @@ describe("Tool Search", () => {
     expect(testing.getReusableCatalogSnapshotCountForTest()).toBe(snapshotsBefore);
   });
 
+  it("serializes a fresh hook-bound catalog schema only once", () => {
+    const codeTool = fakeTool(TOOL_SEARCH_CODE_MODE_TOOL_NAME, "code mode");
+    const config = { tools: { toolSearch: true } } as never;
+    const catalogRef = createToolSearchCatalogRef();
+    const target = pluginTool("fake_hook_bound_schema", "Hook-bound schema probe");
+    let schemaTraversalCount = 0;
+    target.parameters = new Proxy(
+      { type: "object", properties: { value: { type: "string" } } },
+      {
+        ownKeys: (schema) => {
+          schemaTraversalCount += 1;
+          return Reflect.ownKeys(schema);
+        },
+      },
+    );
+
+    const result = applyToolSearchCatalog({
+      tools: [codeTool, target],
+      config,
+      sessionId: "session-hook-bound-schema",
+      runId: "run-hook-bound-schema",
+      catalogRef,
+      toolHookContext: {
+        agentId: "agent-main",
+        sessionId: "session-hook-bound-schema",
+        sessionKey: "agent:main:main",
+        runId: "run-hook-bound-schema",
+      },
+    });
+
+    expect(result.catalogRegistered).toBe(true);
+    expect(catalogRef.current?.entries.map((entry) => entry.name)).toEqual([
+      "fake_hook_bound_schema",
+    ]);
+    expect(schemaTraversalCount).toBe(1);
+  });
+
+  it("preserves last-wins replacement when duplicate catalog ids reorder", () => {
+    const codeTool = fakeTool(TOOL_SEARCH_CODE_MODE_TOOL_NAME, "code mode");
+    const config = { tools: { toolSearch: true } } as never;
+    const catalogRef = createToolSearchCatalogRef();
+    const first = fakeTool("fake_duplicate_id", "First executable");
+    const second = fakeTool("fake_duplicate_id", "Second executable");
+    const params = {
+      config,
+      sessionId: "session-duplicate-id-order",
+      catalogRef,
+    };
+
+    applyToolSearchCatalog({ ...params, tools: [codeTool, first, second] });
+    expect(catalogRef.current?.entries.map((entry) => entry.description)).toEqual([
+      "Second executable",
+    ]);
+
+    const reordered = applyToolSearchCatalog({
+      ...params,
+      tools: [codeTool, second, first],
+    });
+    expect(reordered.catalogReused).toBe(false);
+    expect(catalogRef.current?.entries.map((entry) => entry.description)).toEqual([
+      "First executable",
+    ]);
+  });
+
   it("does not reuse when a same-named tool uses a different executable", () => {
     const codeTool = fakeTool(TOOL_SEARCH_CODE_MODE_TOOL_NAME, "code mode");
     const original = pluginTool("fake_exec_swap", "Stable description");

From ebdb6115ddc0ff1a11c6628429439bfc96710b3c Mon Sep 17 00:00:00 2001
From: ClawSweeper <steipete+clawsweeper@gmail.com>
Date: Fri, 21 Aug 2026 06:54:41 -0700
Subject: [PATCH 002/124] feat(ui): compact mobile chat header (#126788)

* feat(ui): compact mobile chat header

* refactor(ui): move mobile status into session menu

* fix(ui): close mobile status menu before details

* test(ui): follow compact header actions

Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

---------

Co-authored-by: RoboClaw <309084314+roboclaw-bot@users.noreply.github.com>
Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>
---
 config/assertion-safety-baseline.txt          |  2 +-
 ui/src/app/app-shell-view.ts                  |  5 +-
 ui/src/app/device-scope-upgrade.runtime.ts    | 27 +++++-
 ui/src/app/device-scope-upgrade.ts            |  2 +
 ui/src/app/navigation-surface.ts              |  9 +-
 ui/src/e2e/chat-header-axis.e2e.test.ts       |  4 +-
 ui/src/e2e/chat-rail-columns.e2e.test.ts      |  3 +-
 ui/src/e2e/chat-side-panel.test-support.ts    | 11 ++-
 ui/src/e2e/device-scope-upgrade.e2e.test.ts   | 97 ++++++++++++++++++-
 .../e2e/native-nav-sidebar-toggle.e2e.test.ts |  9 +-
 .../plugin-bundled-view-recovery.e2e.test.ts  |  2 +-
 ui/src/e2e/update-confirmation.e2e.test.ts    | 25 ++++-
 ui/src/pages/chat/chat-pane-header.ts         | 86 ++++++++++++++++
 .../chat-header-session-menu.test.ts          | 32 ++++++
 .../components/chat-header-session-menu.ts    | 67 ++++++++++++-
 .../chat/components/chat-pane-header.test.ts  |  8 +-
 .../pages/chat/components/chat-pane-header.ts |  7 +-
 ui/src/styles/chat/split-view.css             | 37 +++++++
 18 files changed, 395 insertions(+), 38 deletions(-)

diff --git a/config/assertion-safety-baseline.txt b/config/assertion-safety-baseline.txt
index 3d4b8c5c2a4e..915e4fe0cddf 100644
--- a/config/assertion-safety-baseline.txt
+++ b/config/assertion-safety-baseline.txt
@@ -4171,7 +4171,7 @@ ui/src/pages/chat/components/chat-composer-slash-menu.ts	1
 ui/src/pages/chat/components/chat-composer-view.ts	1
 ui/src/pages/chat/components/chat-composer.ts	5
 ui/src/pages/chat/components/chat-effort-picker.ts	6
-ui/src/pages/chat/components/chat-header-session-menu.ts	3
+ui/src/pages/chat/components/chat-header-session-menu.ts	2
 ui/src/pages/chat/components/chat-message-attachment-availability.ts	1
 ui/src/pages/chat/components/chat-message-bubble.ts	2
 ui/src/pages/chat/components/chat-message-confirmation.ts	2
diff --git a/ui/src/app/app-shell-view.ts b/ui/src/app/app-shell-view.ts
index bdfa28951861..b5098bbaa408 100644
--- a/ui/src/app/app-shell-view.ts
+++ b/ui/src/app/app-shell-view.ts
@@ -65,6 +65,7 @@ const SCOPE_UPGRADE_BANNER_ELEMENT = {
 function renderScopeUpgradeBanner(
   host: ShellViewHost,
   snapshot: ApplicationContext["gateway"]["snapshot"],
+  compact: boolean,
 ) {
   const state = readScopeUpgradeAvailability(snapshot);
   if (
@@ -78,6 +79,7 @@ function renderScopeUpgradeBanner(
     return html`<openclaw-device-scope-upgrade-banner
       .props=${{
         snapshot,
+        compact,
       }}
     ></openclaw-device-scope-upgrade-banner>`;
   }
@@ -615,10 +617,11 @@ export function renderApplicationShell(host: ShellViewHost) {
           : ""} ${activeRoute === "workboard" ? "content--workboard" : ""}"
         .tabIndex=${-1}
       >
-        ${renderScopeUpgradeBanner(host, gatewaySnapshot)}
+        ${renderScopeUpgradeBanner(host, gatewaySnapshot, mergedChatChrome)}
         ${renderFloatingUpdateCard({
           navigationSurfaceHidden,
           onboarding,
+          compact: mergedChatChrome,
           updateAvailable: overlaySnapshot.updateAvailable,
           updateSchedule: overlaySnapshot.updateSchedule,
           heldUpdateCampaignId: overlaySnapshot.heldUpdateCampaignId,
diff --git a/ui/src/app/device-scope-upgrade.runtime.ts b/ui/src/app/device-scope-upgrade.runtime.ts
index f776db0f99f6..528f0fbce51c 100644
--- a/ui/src/app/device-scope-upgrade.runtime.ts
+++ b/ui/src/app/device-scope-upgrade.runtime.ts
@@ -9,6 +9,7 @@ import {
   dismissScopeUpgradeBanner,
   hasDismissedScopeUpgradeBanner,
   readScopeUpgradeAvailability,
+  SCOPE_UPGRADE_DETAILS_EVENT,
   type ScopeUpgradeState,
 } from "./device-scope-upgrade.ts";
 import type { ApplicationGatewaySnapshot } from "./gateway.ts";
@@ -136,12 +137,25 @@ export class ScopeUpgradeController {
 
 type ScopeUpgradeBannerProps = {
   snapshot: ApplicationGatewaySnapshot;
+  compact: boolean;
 };
 
 class ScopeUpgradeBanner extends OpenClawLightDomContentsElement {
   @property({ attribute: false }) props?: ScopeUpgradeBannerProps;
   private controller?: ScopeUpgradeController;
   private expanded = !hasDismissedScopeUpgradeBanner();
+  private compactExpanded = false;
+
+  private readonly showDetails = () => {
+    this.expanded = true;
+    this.compactExpanded = true;
+    this.requestUpdate();
+  };
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+    window.addEventListener(SCOPE_UPGRADE_DETAILS_EVENT, this.showDetails);
+  }
 
   protected override updated(): void {
     const snapshot = this.props?.snapshot;
@@ -157,6 +171,7 @@ class ScopeUpgradeBanner extends OpenClawLightDomContentsElement {
   }
 
   override disconnectedCallback(): void {
+    window.removeEventListener(SCOPE_UPGRADE_DETAILS_EVENT, this.showDetails);
     this.controller?.dispose();
     this.controller = undefined;
     super.disconnectedCallback();
@@ -177,6 +192,10 @@ class ScopeUpgradeBanner extends OpenClawLightDomContentsElement {
     if (!this.expanded && state.phase === "guidance") {
       return nothing;
     }
+    const compactAvailable = props.compact && !this.compactExpanded;
+    if (compactAvailable && state.phase === "available") {
+      return nothing;
+    }
     if (!this.expanded && state.phase === "available") {
       return html`<div class="scope-upgrade-chip-row">
         <button
@@ -184,13 +203,10 @@ class ScopeUpgradeBanner extends OpenClawLightDomContentsElement {
           type="button"
           aria-expanded="false"
           aria-label=${t("connection.scopeUpgrade.showDetails")}
-          @click=${() => {
-            this.expanded = true;
-            this.requestUpdate();
-          }}
+          @click=${this.showDetails}
         >
           <span class="scope-upgrade-chip__dot" aria-hidden="true"></span>
-          ${t("connection.scopeUpgrade.status")}
+          <span class="scope-upgrade-chip__text">${t("connection.scopeUpgrade.status")}</span>
         </button>
       </div>`;
     }
@@ -247,6 +263,7 @@ class ScopeUpgradeBanner extends OpenClawLightDomContentsElement {
               @click=${() => {
                 dismissScopeUpgradeBanner();
                 this.expanded = false;
+                this.compactExpanded = false;
                 this.requestUpdate();
               }}
             >
diff --git a/ui/src/app/device-scope-upgrade.ts b/ui/src/app/device-scope-upgrade.ts
index bee239a76b7c..46ef32bc8078 100644
--- a/ui/src/app/device-scope-upgrade.ts
+++ b/ui/src/app/device-scope-upgrade.ts
@@ -4,6 +4,8 @@ import { hasOperatorAdminAccess } from "./operator-access.ts";
 
 const SCOPE_UPGRADE_BANNER_DISMISSED_KEY = "openclaw.control.scopeUpgradeBannerDismissed.v1";
 
+export const SCOPE_UPGRADE_DETAILS_EVENT = "openclaw:scope-upgrade-details";
+
 export function hasDismissedScopeUpgradeBanner(): boolean {
   try {
     return globalThis.localStorage?.getItem(SCOPE_UPGRADE_BANNER_DISMISSED_KEY) === "1";
diff --git a/ui/src/app/navigation-surface.ts b/ui/src/app/navigation-surface.ts
index 3915e3ceb8a8..7af2a779f13e 100644
--- a/ui/src/app/navigation-surface.ts
+++ b/ui/src/app/navigation-surface.ts
@@ -17,6 +17,7 @@ export function navigationSurfaceIsHidden(params: {
 export function renderFloatingUpdateCard(params: {
   navigationSurfaceHidden: boolean;
   onboarding: boolean;
+  compact?: boolean;
   updateAvailable: ApplicationContext["overlays"]["snapshot"]["updateAvailable"];
   updateSchedule?: ApplicationContext["overlays"]["snapshot"]["updateSchedule"];
   heldUpdateCampaignId?: string | null;
@@ -35,10 +36,10 @@ export function renderFloatingUpdateCard(params: {
 }) {
   // A stale client must always have a visible refresh action, including during
   // onboarding, even though update-available actions stay hidden there.
-  const showAttention = params.navigationSurfaceHidden && !params.onboarding;
-  const showUpdateCard = params.onboarding
-    ? params.refreshRequired
-    : params.navigationSurfaceHidden;
+  const showAttention = params.navigationSurfaceHidden && !params.onboarding && !params.compact;
+  const showUpdateCard =
+    !params.compact &&
+    (params.onboarding ? params.refreshRequired : params.navigationSurfaceHidden);
   if (!showAttention && !showUpdateCard) {
     return nothing;
   }
diff --git a/ui/src/e2e/chat-header-axis.e2e.test.ts b/ui/src/e2e/chat-header-axis.e2e.test.ts
index caf112ae158b..b71fe3527d4b 100644
--- a/ui/src/e2e/chat-header-axis.e2e.test.ts
+++ b/ui/src/e2e/chat-header-axis.e2e.test.ts
@@ -66,14 +66,14 @@ suite.define(() => {
             nav: centerY(".chat-pane__nav-toggle svg"),
             projectIcon: centerY(".workspace-icon"),
             projectText: centerY(".chat-pane__workspace-chip span"),
-            search: centerY(".chat-pane__palette-open svg"),
+            menu: centerY(".chat-header-session-menu__trigger svg"),
             separator: centerY(".chat-pane__crumb-sep"),
             parentText: centerY(".chat-pane__parent-session-text"),
             sessionText: centerY(".chat-pane__session-title-text"),
           };
         });
 
-        expect(Math.abs(centers.search - centers.nav), JSON.stringify(centers)).toBeLessThanOrEqual(
+        expect(Math.abs(centers.menu - centers.nav), JSON.stringify(centers)).toBeLessThanOrEqual(
           0.1,
         );
         for (const center of [
diff --git a/ui/src/e2e/chat-rail-columns.e2e.test.ts b/ui/src/e2e/chat-rail-columns.e2e.test.ts
index b44551ef55a7..cc73fbae7777 100644
--- a/ui/src/e2e/chat-rail-columns.e2e.test.ts
+++ b/ui/src/e2e/chat-rail-columns.e2e.test.ts
@@ -902,8 +902,7 @@ suite.define(() => {
         const gateway = await installMockGateway(page, scenario());
         await page.goto(`${suite.server.baseUrl}chat`);
         await page.locator(".chat-group").first().waitFor();
-        await page.locator(".chat-side-panel-toggle").click();
-        await openFromEmpty(page, "Files");
+        await activateChatHeaderPanelAction(page, "Show session files");
         await openFromPlus(page, "Terminal");
         await openFromPlus(page, "Side chat");
         await selectTab(page, "Side chat");
diff --git a/ui/src/e2e/chat-side-panel.test-support.ts b/ui/src/e2e/chat-side-panel.test-support.ts
index b0204b3c25ef..e2d3e1b509ee 100644
--- a/ui/src/e2e/chat-side-panel.test-support.ts
+++ b/ui/src/e2e/chat-side-panel.test-support.ts
@@ -26,11 +26,14 @@ export async function activateChatHeaderPanelAction(page: Page, label: string):
     .locator('wa-dropdown-item[value^="quick:panels:"]')
     .filter({ hasText: label });
   if (!(await action.isVisible())) {
-    await menu
-      .locator(".session-menu__text")
-      .filter({ hasText: /^Panels$/ })
-      .hover();
+    const panels = menu.locator(".session-menu__text").filter({ hasText: /^Panels$/ });
+    if ((await menu.locator("wa-dropdown.chat-header-session-menu--compact").count()) > 0) {
+      await panels.click();
+    } else {
+      await panels.hover();
+    }
   }
+  await action.waitFor({ state: "visible" });
   const afterHide = menu.locator("wa-dropdown").evaluate(
     (dropdown) =>
       new Promise<void>((resolve) => {
diff --git a/ui/src/e2e/device-scope-upgrade.e2e.test.ts b/ui/src/e2e/device-scope-upgrade.e2e.test.ts
index c842f46b446e..a67abab1ab37 100644
--- a/ui/src/e2e/device-scope-upgrade.e2e.test.ts
+++ b/ui/src/e2e/device-scope-upgrade.e2e.test.ts
@@ -1,4 +1,4 @@
-import { mkdir } from "node:fs/promises";
+import { copyFile, mkdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { chromium, type Browser, type BrowserContext, type Page, type Route } from "playwright";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
@@ -78,6 +78,39 @@ async function createContext(): Promise<BrowserContext> {
   return context;
 }
 
+async function createProofContext(
+  viewport: { width: number; height: number },
+  label: string,
+): Promise<{ context: BrowserContext; page: Page; rawVideoDir: string | null }> {
+  const rawVideoDir = proofDir ? path.join(proofDir, "raw-video", label) : null;
+  if (rawVideoDir) {
+    await mkdir(rawVideoDir, { recursive: true });
+  }
+  const context = await browser.newContext({
+    locale: "en-US",
+    ...(rawVideoDir ? { recordVideo: { dir: rawVideoDir, size: viewport } } : {}),
+    serviceWorkers: "block",
+    viewport,
+  });
+  openContexts.add(context);
+  return { context, page: await context.newPage(), rawVideoDir };
+}
+
+async function closeProofContext(
+  proof: { context: BrowserContext; page: Page; rawVideoDir: string | null },
+  label: string,
+): Promise<void> {
+  const video = proof.page.video();
+  openContexts.delete(proof.context);
+  await proof.context.close();
+  if (proofDir && video) {
+    await copyFile(await video.path(), path.join(proofDir, `${label}.webm`));
+  }
+  if (proof.rawVideoDir) {
+    await rm(proof.rawVideoDir, { force: true, recursive: true });
+  }
+}
+
 async function waitForLayoutSettled(page: Page, selector: string): Promise<void> {
   // content-visibility, grid transitions, and lazy styles can defer layout beyond
   // a fixed rAF pair. Measure the owning geometry until two frames agree.
@@ -133,6 +166,68 @@ describeControlUiE2e("Control UI live device scope upgrade", () => {
     openContexts.clear();
   });
 
+  it("keeps mobile status inside the overflow menu while leaving desktop chrome unchanged", async () => {
+    const mobile = await createProofContext({ width: 390, height: 844 }, "mobile");
+    try {
+      const gateway = await installMockGateway(mobile.page, { operatorScopes: LIMITED_SCOPES });
+      await mobile.page.goto(`${server.baseUrl}chat`);
+      await gateway.emitGatewayEvent("update.available", {
+        updateAvailable: {
+          channel: "stable",
+          currentVersion: "1.0.0",
+          latestVersion: "2.0.0",
+        },
+      });
+      const header = mobile.page.locator(".chat-pane__header").first();
+      const menu = mobile.page.locator(".chat-header-session-menu__trigger");
+      await header.waitFor();
+      await menu.waitFor();
+      expect(await mobile.page.locator(".chat-pane__palette-open").count()).toBe(0);
+      expect(await mobile.page.locator(".chat-side-panel-toggle").count()).toBe(0);
+      expect(await mobile.page.locator(".scope-upgrade-chip").count()).toBe(0);
+      expect(await mobile.page.locator(".sidebar-attention--floating").count()).toBe(0);
+      expect(await mobile.page.locator(".sidebar-update-card--floating").count()).toBe(0);
+      expect(await mobile.page.locator(".chat-header-session-menu__status-dot").count()).toBe(1);
+      await captureProof(mobile.page, "mobile-compact-header.png");
+      await mobile.page.waitForTimeout(500);
+      await menu.click();
+      const status = mobile.page.getByText("Limited access", { exact: true });
+      await status.waitFor();
+      await mobile.page.getByText("Update available v2.0.0", { exact: true }).waitFor();
+      await captureProof(mobile.page, "mobile-status-menu.png");
+      await mobile.page.waitForTimeout(500);
+      await status.click();
+      await mobile.page.getByText("This browser has limited access.", { exact: true }).waitFor();
+      await mobile.page
+        .locator(".chat-header-session-menu--compact wa-dropdown-item")
+        .first()
+        .waitFor({ state: "hidden" });
+      await captureProof(mobile.page, "mobile-access-details.png");
+      await mobile.page.waitForTimeout(700);
+      await mobile.page.getByRole("button", { name: "Collapse limited access banner" }).click();
+      await menu.waitFor();
+      await mobile.page.waitForTimeout(500);
+    } finally {
+      await closeProofContext(mobile, "mobile-compact-header");
+    }
+
+    const desktop = await createProofContext({ width: 1280, height: 900 }, "desktop");
+    try {
+      await installMockGateway(desktop.page, { operatorScopes: LIMITED_SCOPES });
+      await desktop.page.goto(`${server.baseUrl}chat`);
+      await desktop.page.getByText("This browser has limited access.", { exact: true }).waitFor();
+      await desktop.page.locator(".shell-chrome-controls__search").first().waitFor();
+      await desktop.page.locator(".chat-side-panel-toggle").first().waitFor();
+      await captureProof(desktop.page, "desktop-unchanged.png");
+      await desktop.page.waitForTimeout(500);
+      await desktop.page.getByRole("button", { name: "Collapse limited access banner" }).click();
+      await desktop.page.getByRole("button", { name: "Show limited access details" }).waitFor();
+      await desktop.page.waitForTimeout(500);
+    } finally {
+      await closeProofContext(desktop, "desktop-unchanged");
+    }
+  });
+
   it("requests admin explicitly, shows pending repair guidance, and reconnects approved", async () => {
     const context = await createContext();
     const page = await context.newPage();
diff --git a/ui/src/e2e/native-nav-sidebar-toggle.e2e.test.ts b/ui/src/e2e/native-nav-sidebar-toggle.e2e.test.ts
index 3faed48e49d3..6afa7641603f 100644
--- a/ui/src/e2e/native-nav-sidebar-toggle.e2e.test.ts
+++ b/ui/src/e2e/native-nav-sidebar-toggle.e2e.test.ts
@@ -322,7 +322,7 @@ suite.define(() => {
     expect(metrics).toEqual({ bodyScrollTop: 0, htmlScrollTop: 0, rootScrollY: 0 });
   });
 
-  it("moves drawer and search controls into the narrow chat title bar", async () => {
+  it("keeps drawer and search reachable from the narrow chat title bar", async () => {
     const page = await openPage({ nativeNav: false, width: 900 });
     const header = page.locator(".chat-pane__header").first();
     await expect
@@ -332,9 +332,10 @@ suite.define(() => {
     await expect
       .poll(() => header.getByRole("button", { name: "Expand sidebar" }).isVisible())
       .toBe(true);
-    await expect
-      .poll(() => header.getByRole("button", { name: "Open command palette" }).isVisible())
-      .toBe(true);
+    await expect.poll(() => header.locator(".chat-pane__palette-open").count()).toBe(0);
+    await header.locator(".chat-header-session-menu__trigger").click();
+    await page.getByText("Open command palette", { exact: true }).click();
+    await page.locator(".cmd-palette__input").waitFor({ state: "visible" });
   });
 
   it("keeps the mobile drawer modal, keyboard-contained, and focus-restoring", async () => {
diff --git a/ui/src/e2e/plugin-bundled-view-recovery.e2e.test.ts b/ui/src/e2e/plugin-bundled-view-recovery.e2e.test.ts
index 0c71ff5f1514..6f66ffceb239 100644
--- a/ui/src/e2e/plugin-bundled-view-recovery.e2e.test.ts
+++ b/ui/src/e2e/plugin-bundled-view-recovery.e2e.test.ts
@@ -7,7 +7,7 @@ import { installMockGateway } from "../test-helpers/control-ui-e2e.ts";
 import { createControlUiE2eSuite } from "./control-ui-e2e-suite.test-support.ts";
 
 const artifactDir = path.resolve(".artifacts/control-ui-e2e/plugin-bundled-view-recovery");
-const bundledChunk = /\/assets\/[^/]+\.js(?:\?.*)?$/;
+const bundledChunk = /\/assets\/logbook-view-[^/]+\.js(?:\?.*)?$/;
 
 const suite = createControlUiE2eSuite({
   name: "Control UI bundled plugin lazy-view recovery",
diff --git a/ui/src/e2e/update-confirmation.e2e.test.ts b/ui/src/e2e/update-confirmation.e2e.test.ts
index 271f560a99ac..1e01b54c5fa7 100644
--- a/ui/src/e2e/update-confirmation.e2e.test.ts
+++ b/ui/src/e2e/update-confirmation.e2e.test.ts
@@ -27,22 +27,32 @@ function confirmationCopy(page: Page) {
   return page.locator("openclaw-modal-dialog");
 }
 
-async function openUpdateCard(page: Page, baseUrl: string) {
+async function openUpdateCard(page: Page, baseUrl: string, compact = false) {
   const gateway = await installMockGateway(page, {
     methodResponses: { "update.run": UPDATE_RUN_RESPONSE },
   });
   expect((await page.goto(`${baseUrl}chat`))?.status()).toBe(200);
   await gateway.waitForRequest("chat.startup");
   await gateway.emitGatewayEvent("update.available", { updateAvailable: UPDATE_AVAILABLE });
+  if (compact) {
+    await page.locator(".chat-header-session-menu__trigger").click();
+    const updateButton = page.getByText("Update available v2.0.0", { exact: true });
+    await updateButton.waitFor({ timeout: 10_000 });
+    return { compact, gateway, updateButton };
+  }
   const updateButton = page.locator(
     '[data-attention-kind="updateAvailable"] .sidebar-attention__open:visible',
   );
   await updateButton.waitFor({ timeout: 10_000 });
-  return { gateway, updateButton };
+  return { compact, gateway, updateButton };
 }
 
-async function openConfirmationFromAlert(page: Page, updateButton: Locator) {
+async function openConfirmationFromAlert(page: Page, updateButton: Locator, compact = false) {
   await updateButton.click();
+  if (compact) {
+    await page.getByRole("button", { name: "Update now", exact: true }).click();
+    return;
+  }
   const action = page
     .locator(".custodian__alert-card")
     .getByRole("button", { name: "Update and restart", exact: true });
@@ -98,8 +108,13 @@ suite.define(() => {
           viewport: variant.viewport,
         },
         async ({ page }) => {
-          const { gateway, updateButton } = await openUpdateCard(page, suite.server.baseUrl);
-          await openConfirmationFromAlert(page, updateButton);
+          const compact = variant.viewport.width < 600;
+          const { gateway, updateButton } = await openUpdateCard(
+            page,
+            suite.server.baseUrl,
+            compact,
+          );
+          await openConfirmationFromAlert(page, updateButton, compact);
           await page.getByRole("dialog").waitFor();
           expect(
             await confirmationCopy(page)
diff --git a/ui/src/pages/chat/chat-pane-header.ts b/ui/src/pages/chat/chat-pane-header.ts
index e022504b1b75..8f728e580e00 100644
--- a/ui/src/pages/chat/chat-pane-header.ts
+++ b/ui/src/pages/chat/chat-pane-header.ts
@@ -4,7 +4,17 @@ import { buildControlUiResourcePath } from "../../../../src/gateway/control-ui-r
 import type { GatewaySessionRow } from "../../api/types.ts";
 import { isDesktopPanelAvailable } from "../../app/app-shell-chrome.ts";
 import { resolveControlUiAuthCandidates } from "../../app/control-ui-auth.ts";
+import {
+  hasDismissedScopeUpgradeBanner,
+  readScopeUpgradeAvailability,
+  SCOPE_UPGRADE_DETAILS_EVENT,
+} from "../../app/device-scope-upgrade.ts";
 import { hasOperatorAdminAccess } from "../../app/operator-access.ts";
+import {
+  formatUpdateCampaignLabel,
+  formatUpdateTargetLabel,
+} from "../../app/update-overlay-helpers.ts";
+import { COMMAND_PALETTE_OPEN_EVENT } from "../../components/command-palette-contract.ts";
 import { icons } from "../../components/icons.ts";
 import { sessionMenuReasons } from "../../components/session-menu-access.ts";
 import { listAssignableSessionOwners } from "../../components/session-owner-chip.ts";
@@ -32,6 +42,7 @@ import type {
   HeaderMenuAction,
   HeaderMenuActionKind,
   HeaderMenuQuickAction,
+  HeaderMenuStatusAction,
 } from "./components/chat-header-session-menu.ts";
 import {
   canRevealSessionWorkspace,
@@ -68,6 +79,78 @@ export abstract class ChatPaneHeader extends ChatPaneDiscussion {
     };
   }
 
+  private compactHeaderStatusActions(): HeaderMenuStatusAction[] {
+    if (!this.narrow) {
+      return [];
+    }
+    const actions: HeaderMenuStatusAction[] = [];
+    const scopeState = readScopeUpgradeAvailability(this.context.gateway.snapshot);
+    const scopeStatusVisible =
+      scopeState.phase !== "hidden" &&
+      !(scopeState.phase === "guidance" && hasDismissedScopeUpgradeBanner());
+    if (scopeStatusVisible) {
+      actions.push({
+        id: "access",
+        label: t("connection.scopeUpgrade.status"),
+        icon: icons.shieldQuestion,
+        tone: "warn",
+        onActivate: () => window.dispatchEvent(new Event(SCOPE_UPGRADE_DETAILS_EVENT)),
+      });
+    }
+
+    const overlay = this.context.overlays.snapshot;
+    if (overlay.controlUiRefreshRequired) {
+      actions.push({
+        id: "refresh",
+        label: `${t("chat.sidebar.serverUpdatedTitle")} · ${t(
+          "chat.sidebar.serverUpdatedRefresh",
+        )}`,
+        icon: icons.refresh,
+        tone: "info",
+        onActivate: () => globalThis.location.reload(),
+      });
+      return actions;
+    }
+
+    const campaignLabel = formatUpdateCampaignLabel(overlay.updateSchedule);
+    const targetLabel = formatUpdateTargetLabel(overlay.updateSchedule, overlay.updateAvailable);
+    const updateBusy = overlay.updateRunning || overlay.updateReconciliationPending;
+    const update = overlay.updateAvailable;
+    const target = overlay.updateSchedule?.target;
+    const updateAvailable = Boolean(
+      update &&
+      !overlay.updateSchedule?.campaign &&
+      !overlay.updateStatusBanner &&
+      (update.latestVersion !== update.currentVersion ||
+        (target?.kind === "git" && target.commitsBehind > 0)),
+    );
+    const updateLabel = overlay.updateStatusBanner?.text
+      ? overlay.updateStatusBanner.text
+      : campaignLabel
+        ? targetLabel
+          ? t("updates.sidebar.campaignTarget", { status: campaignLabel, target: targetLabel })
+          : campaignLabel
+        : updateBusy
+          ? t("updates.sidebar.updating")
+          : updateAvailable
+            ? t("updates.page.available", { target: targetLabel ?? update?.latestVersion ?? "" })
+            : null;
+    if (updateLabel) {
+      actions.push({
+        id: "update",
+        label: updateLabel,
+        icon: overlay.updateStatusBanner
+          ? icons.alertTriangle
+          : updateBusy
+            ? icons.refresh
+            : icons.download,
+        tone: overlay.updateStatusBanner?.tone ?? (updateBusy ? "info" : "warn"),
+        onActivate: () => this.context.navigate("updates"),
+      });
+    }
+    return actions;
+  }
+
   protected renderPaneHeader(
     sessionWorkspace: SessionWorkspaceProps,
     backgroundTasks: BackgroundTasksProps,
@@ -468,6 +551,7 @@ export abstract class ChatPaneHeader extends ChatPaneDiscussion {
               .settings=${this.state.settings}
               .panelActions=${panelMenuActions}
               .layoutActions=${layoutMenuActions}
+              .statusActions=${this.compactHeaderStatusActions()}
               .ownerOptions=${ownerOptions}
               .selfOwner=${selfOwner}
               .currentOwnerId=${row.owner?.actor.id ?? null}
@@ -479,6 +563,8 @@ export abstract class ChatPaneHeader extends ChatPaneDiscussion {
               .onOpen=${() => {
                 void this.loadHeaderMenuData(row, agentWorkspace, workspaceGit);
               }}
+              .onOpenCommandPalette=${() =>
+                window.dispatchEvent(new Event(COMMAND_PALETTE_OPEN_EVENT))}
               .onSettingsChange=${this.state.applySettings}
               .onAction=${(action: HeaderMenuAction) => this.handleHeaderSessionAction(action, row)}
             ></openclaw-chat-header-session-menu>`
diff --git a/ui/src/pages/chat/components/chat-header-session-menu.test.ts b/ui/src/pages/chat/components/chat-header-session-menu.test.ts
index fdce13785a30..04446780ba64 100644
--- a/ui/src/pages/chat/components/chat-header-session-menu.test.ts
+++ b/ui/src/pages/chat/components/chat-header-session-menu.test.ts
@@ -10,6 +10,7 @@ import type {
   HeaderMenuAction,
   HeaderMenuActionKind,
   HeaderMenuQuickAction,
+  HeaderMenuStatusAction,
 } from "./chat-header-session-menu.ts";
 
 type HeaderMenuElement = HTMLElement & { updateComplete: Promise<boolean> };
@@ -50,6 +51,7 @@ async function mountMenu(
     settings?: UiSettings;
     panelActions?: HeaderMenuQuickAction[];
     layoutActions?: HeaderMenuQuickAction[];
+    statusActions?: HeaderMenuStatusAction[];
     ownerOptions?: SessionOwnerOption[];
     selfOwner?: SessionOwnerOption | null;
     currentOwnerId?: string | null;
@@ -59,6 +61,7 @@ async function mountMenu(
     archiveAllowed?: boolean;
     deleteAllowed?: boolean;
     onOpen?: () => void;
+    onOpenCommandPalette?: () => void;
     onSettingsChange?: (patch: Partial<UiSettings>) => void;
     onAction?: (action: HeaderMenuAction) => void;
   } = {},
@@ -77,6 +80,7 @@ async function mountMenu(
       .settings=${options.settings ?? settings()}
       .panelActions=${options.panelActions ?? []}
       .layoutActions=${options.layoutActions ?? []}
+      .statusActions=${options.statusActions ?? []}
       .ownerOptions=${options.ownerOptions ?? []}
       .selfOwner=${options.selfOwner ?? null}
       .currentOwnerId=${options.currentOwnerId ?? null}
@@ -86,6 +90,7 @@ async function mountMenu(
       .archiveAllowed=${options.archiveAllowed ?? true}
       .deleteAllowed=${options.deleteAllowed ?? true}
       .onOpen=${options.onOpen ?? (() => {})}
+      .onOpenCommandPalette=${options.onOpenCommandPalette ?? (() => {})}
       .onSettingsChange=${options.onSettingsChange ?? (() => {})}
       .onAction=${options.onAction ?? (() => {})}
     ></openclaw-chat-header-session-menu>`,
@@ -275,6 +280,8 @@ describe("chat header session menu", () => {
 
   it("drills into compact menu groups without rendering side flyouts", async () => {
     const showTasks = vi.fn();
+    const showAccess = vi.fn();
+    const onOpenCommandPalette = vi.fn();
     const onSettingsChange = vi.fn<(patch: Partial<UiSettings>) => void>();
     const onAction = vi.fn<(action: HeaderMenuAction) => void>();
     const ada = { type: "human", id: "profile-ada", label: "Ada" } as const;
@@ -299,9 +306,19 @@ describe("chat header session menu", () => {
           onActivate: vi.fn(),
         },
       ],
+      statusActions: [
+        {
+          id: "access",
+          label: "Limited access",
+          icon: icons.shieldQuestion,
+          tone: "warn",
+          onActivate: showAccess,
+        },
+      ],
       ownerOptions: [ada, research],
       selfOwner: ada,
       currentOwnerId: research.id,
+      onOpenCommandPalette,
       onSettingsChange,
       onAction,
     });
@@ -310,6 +327,8 @@ describe("chat header session menu", () => {
       menu.querySelectorAll<MenuItemElement>(":scope > wa-dropdown > wa-dropdown-item"),
     ).map(itemLabel);
     expect(rootLabels).toEqual([
+      "Open command palette",
+      "Limited access",
       "Open in",
       "Panels",
       "Layout",
@@ -322,6 +341,19 @@ describe("chat header session menu", () => {
       "Delete…",
     ]);
     expect(menu.querySelector("[slot='submenu']")).toBeNull();
+    expect(
+      menu.querySelector('.chat-header-session-menu__status-dot[data-tone="warn"]'),
+    ).not.toBeNull();
+
+    select(menu, "open-command-palette");
+    expect(onOpenCommandPalette).toHaveBeenCalledOnce();
+    const dropdown = menu.querySelector<HTMLElement & { open: boolean }>("wa-dropdown");
+    if (dropdown) {
+      dropdown.open = true;
+    }
+    select(menu, "status:access");
+    expect(showAccess).toHaveBeenCalledOnce();
+    expect(dropdown?.open).toBe(false);
 
     select(menu, "compact:open-view");
     await menu.updateComplete;
diff --git a/ui/src/pages/chat/components/chat-header-session-menu.ts b/ui/src/pages/chat/components/chat-header-session-menu.ts
index c191045f1748..7c809be28320 100644
--- a/ui/src/pages/chat/components/chat-header-session-menu.ts
+++ b/ui/src/pages/chat/components/chat-header-session-menu.ts
@@ -32,9 +32,20 @@ export type HeaderMenuQuickAction = {
   onActivate: () => void;
 };
 
+export type HeaderMenuStatusAction = {
+  id: string;
+  label: string;
+  icon: TemplateResult;
+  tone: "danger" | "warn" | "info";
+  onActivate: () => void;
+};
+
 const EMPTY_SETTINGS = {} as UiSettings;
 
 type CompactMenuView = "root" | "open-in" | "panels" | "layout" | "assign-owner" | "view";
+type MenuSelectEvent = CustomEvent<{ item: { value?: string } }> & {
+  currentTarget: HTMLElement & { open: boolean };
+};
 
 const COMPACT_MENU_VIEW_BY_VALUE: Record<string, CompactMenuView> = {
   "compact:back": "root",
@@ -55,6 +66,7 @@ class ChatHeaderSessionMenu extends OpenClawLightDomElement {
   @property({ attribute: false }) settings: UiSettings = EMPTY_SETTINGS;
   @property({ attribute: false }) panelActions: HeaderMenuQuickAction[] = [];
   @property({ attribute: false }) layoutActions: HeaderMenuQuickAction[] = [];
+  @property({ attribute: false }) statusActions: HeaderMenuStatusAction[] = [];
   @property({ attribute: false }) ownerOptions: readonly SessionOwnerOption[] = [];
   @property({ attribute: false }) selfOwner: SessionOwnerOption | null = null;
   @property({ attribute: false }) currentOwnerId: string | null = null;
@@ -66,6 +78,7 @@ class ChatHeaderSessionMenu extends OpenClawLightDomElement {
   @property({ attribute: false }) archiveAllowed = false;
   @property({ attribute: false }) deleteAllowed = false;
   @property({ attribute: false }) onOpen: () => void = () => {};
+  @property({ attribute: false }) onOpenCommandPalette: () => void = () => {};
   @property({ attribute: false }) onSettingsChange: (patch: Partial<UiSettings>) => void = () => {};
   @property({ attribute: false }) onAction: (action: HeaderMenuAction) => void = () => {};
   @state() private compactView: CompactMenuView = "root";
@@ -78,7 +91,7 @@ class ChatHeaderSessionMenu extends OpenClawLightDomElement {
     return this.actionDisabledReasons[kind] ?? nothing;
   }
 
-  private readonly handleSelect = (event: CustomEvent<{ item: { value?: string } }>) => {
+  private readonly handleSelect = (event: MenuSelectEvent) => {
     const value = event.detail.item.value;
     if (!value) {
       return;
@@ -92,6 +105,20 @@ class ChatHeaderSessionMenu extends OpenClawLightDomElement {
       });
       return;
     }
+    if (value === "open-command-palette") {
+      this.onOpenCommandPalette();
+      return;
+    }
+    if (value.startsWith("status:")) {
+      const action = this.statusActions.find(
+        (candidate) => candidate.id === value.slice("status:".length),
+      );
+      if (action) {
+        event.currentTarget.open = false;
+        action.onActivate();
+      }
+      return;
+    }
     if (value.startsWith("quick:")) {
       const [, group, id] = value.split(":");
       const actions = group === "panels" ? this.panelActions : this.layoutActions;
@@ -139,7 +166,7 @@ class ChatHeaderSessionMenu extends OpenClawLightDomElement {
     ) {
       if (!this.actionDisabled(value, value === "fork" && this.forkDisabled)) {
         if (value === "continue-in-terminal") {
-          (event.currentTarget as HTMLElement & { open: boolean }).open = false;
+          event.currentTarget.open = false;
         }
         this.onAction({ kind: value });
       }
@@ -293,6 +320,31 @@ class ChatHeaderSessionMenu extends OpenClawLightDomElement {
 
   private renderRootView() {
     return html`
+      ${this.compact
+        ? html`<wa-dropdown-item class="session-menu__item" value="open-command-palette">
+              <span slot="icon" class="session-menu__icon" aria-hidden="true">${icons.search}</span>
+              <span class="session-menu__text">${t("chat.openCommandPalette")}</span>
+            </wa-dropdown-item>
+            <div class="session-menu__separator" role="separator"></div>`
+        : nothing}
+      ${this.compact && this.statusActions.length > 0
+        ? html`${this.statusActions.map(
+              (action) => html`<wa-dropdown-item
+                class="session-menu__item chat-header-session-menu__status-item"
+                value=${`status:${action.id}`}
+              >
+                <span
+                  slot="icon"
+                  class="session-menu__icon chat-header-session-menu__status-icon"
+                  data-tone=${action.tone}
+                  aria-hidden="true"
+                  >${action.icon}</span
+                >
+                <span class="session-menu__text">${action.label}</span>
+              </wa-dropdown-item>`,
+            )}
+            <div class="session-menu__separator" role="separator"></div>`
+        : nothing}
       ${this.worktreePath
         ? html`
             ${this.compact
@@ -421,6 +473,10 @@ class ChatHeaderSessionMenu extends OpenClawLightDomElement {
 
   override render() {
     const menuLabel = t("chat.sidebar.sessionMenu", { session: this.sessionLabel });
+    const statusTone =
+      this.statusActions.find((action) => action.tone === "danger")?.tone ??
+      this.statusActions.find((action) => action.tone === "warn")?.tone ??
+      this.statusActions[0]?.tone;
     return html`
       <wa-dropdown
         class=${`session-menu chat-header-session-menu${this.compact ? " chat-header-session-menu--compact" : ""}`}
@@ -439,6 +495,13 @@ class ChatHeaderSessionMenu extends OpenClawLightDomElement {
           aria-haspopup="menu"
         >
           ${icons.moreHorizontal}
+          ${this.compact && statusTone
+            ? html`<span
+                class="chat-header-session-menu__status-dot"
+                data-tone=${statusTone}
+                aria-hidden="true"
+              ></span>`
+            : nothing}
         </button>
         ${this.compact && this.compactView !== "root"
           ? this.renderCompactView()
diff --git a/ui/src/pages/chat/components/chat-pane-header.test.ts b/ui/src/pages/chat/components/chat-pane-header.test.ts
index 067daea491dd..6acce36df692 100644
--- a/ui/src/pages/chat/components/chat-pane-header.test.ts
+++ b/ui/src/pages/chat/components/chat-pane-header.test.ts
@@ -305,7 +305,7 @@ describe("chat pane header", () => {
     expect(actions?.querySelector(".chat-pane__close-pane")).not.toBeNull();
   });
 
-  it("keeps persistent surface actions in a narrow header", () => {
+  it("moves narrow session actions into the compact menu", () => {
     const { container } = mount({
       narrow: true,
       mergedChrome: true,
@@ -316,9 +316,10 @@ describe("chat pane header", () => {
       workspaceAction: html`<button data-action="workspace"></button>`,
       sessionRailAction: html`<button data-action="rail"></button>`,
       sessionMenuAction: html`<button data-action="session-menu"></button>`,
+      onOpenSplitView: vi.fn(),
     });
 
-    expect(container.querySelector('[data-action="persistent-surface"]')).not.toBeNull();
+    expect(container.querySelector('[data-action="persistent-surface"]')).toBeNull();
     expect(container.querySelector('[data-action="discussion"]')).toBeNull();
     expect(container.querySelector('[data-action="diff"]')).toBeNull();
     expect(container.querySelector('[data-action="tasks"]')).toBeNull();
@@ -326,7 +327,8 @@ describe("chat pane header", () => {
     expect(container.querySelector('[data-action="rail"]')).toBeNull();
     expect(container.querySelector('[data-action="session-menu"]')).not.toBeNull();
     expect(container.querySelector(".chat-pane__nav-toggle")).not.toBeNull();
-    expect(container.querySelector(".chat-pane__palette-open")).not.toBeNull();
+    expect(container.querySelector(".chat-pane__palette-open")).toBeNull();
+    expect(container.querySelector(".chat-open-split-view")).toBeNull();
   });
 
   it("keeps narrow catalog panel shortcuts visible without a session menu", () => {
diff --git a/ui/src/pages/chat/components/chat-pane-header.ts b/ui/src/pages/chat/components/chat-pane-header.ts
index 1f1844dd99cb..46a09e5230a5 100644
--- a/ui/src/pages/chat/components/chat-pane-header.ts
+++ b/ui/src/pages/chat/components/chat-pane-header.ts
@@ -536,12 +536,13 @@ export function renderChatPaneHeader(props: ChatPaneHeaderProps) {
         : nothing}
       ${renderGatewayPicker(props)}
       <div class="chat-pane__actions">
-        ${props.panelActions} ${compactSessionActions ? nothing : props.discussionAction}
+        ${compactSessionActions ? nothing : props.panelActions}
+        ${compactSessionActions ? nothing : props.discussionAction}
         ${props.catalog || compactSessionActions
           ? nothing
           : html`${props.diffAction} ${props.backgroundTasksAction} ${props.workspaceAction}
             ${props.sessionRailAction}`}
-        ${props.onOpenSplitView
+        ${props.onOpenSplitView && !compactSessionActions
           ? html`<openclaw-tooltip .content=${t("chat.splitView.open")}>
               <button
                 class="btn btn--ghost btn--icon chat-icon-btn chat-open-split-view"
@@ -589,7 +590,7 @@ export function renderChatPaneHeader(props: ChatPaneHeaderProps) {
               </button>
             </openclaw-tooltip>`
           : nothing}
-        ${props.mergedChrome
+        ${props.mergedChrome && !compactSessionActions
           ? html`<openclaw-tooltip .content=${t("chat.openCommandPalette")}>
               <button
                 class="btn btn--ghost btn--icon chat-icon-btn chat-pane__palette-open"
diff --git a/ui/src/styles/chat/split-view.css b/ui/src/styles/chat/split-view.css
index a683656a5008..e80ebac70cc1 100644
--- a/ui/src/styles/chat/split-view.css
+++ b/ui/src/styles/chat/split-view.css
@@ -759,6 +759,43 @@ openclaw-chat-pane {
   min-height: 44px;
 }
 
+.chat-header-session-menu__trigger {
+  position: relative;
+}
+
+.chat-header-session-menu__status-dot {
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  width: 6px;
+  height: 6px;
+  border: 1px solid var(--chat-surface);
+  border-radius: 999px;
+  background: var(--info);
+}
+
+.chat-header-session-menu__status-dot[data-tone="warn"],
+.chat-header-session-menu__status-icon[data-tone="warn"] {
+  color: var(--warn);
+}
+
+.chat-header-session-menu__status-dot[data-tone="warn"] {
+  background: var(--warn);
+}
+
+.chat-header-session-menu__status-dot[data-tone="danger"],
+.chat-header-session-menu__status-icon[data-tone="danger"] {
+  color: var(--danger);
+}
+
+.chat-header-session-menu__status-dot[data-tone="danger"] {
+  background: var(--danger);
+}
+
+.chat-header-session-menu__status-icon[data-tone="info"] {
+  color: var(--info);
+}
+
 .chat-header-session-menu--compact .session-menu__back {
   z-index: 1;
   position: sticky;

From 7498391c81378a3cad4314b391b726f20dd89596 Mon Sep 17 00:00:00 2001
From: ClawSweeper <steipete+clawsweeper@gmail.com>
Date: Fri, 21 Aug 2026 06:55:32 -0700
Subject: [PATCH 003/124] improve: show condition activity in automation
 history (#127200)

Co-authored-by: RoboClaw <309084314+roboclaw-bot@users.noreply.github.com>
Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>
---
 ui/src/e2e/cron-trigger-filter.e2e.test.ts | 15 +++++
 ui/src/i18n/locales/en.ts                  | 14 +++++
 ui/src/pages/cron/view-runs.ts             | 61 +++++++++++++++++++-
 ui/src/pages/cron/view.ts                  | 11 +++-
 ui/src/styles/cron.css                     | 67 ++++++++++++++++++++++
 5 files changed, 165 insertions(+), 3 deletions(-)

diff --git a/ui/src/e2e/cron-trigger-filter.e2e.test.ts b/ui/src/e2e/cron-trigger-filter.e2e.test.ts
index 9ee9651a2551..6690ba3c9496 100644
--- a/ui/src/e2e/cron-trigger-filter.e2e.test.ts
+++ b/ui/src/e2e/cron-trigger-filter.e2e.test.ts
@@ -25,6 +25,10 @@ const conditionalJob = {
   name: "Conditional job",
   payload: { kind: "systemEvent", text: "conditional" },
   trigger: { script: "json({ fire: true })" },
+  state: {
+    triggerEvalCount: 42,
+    lastTriggerEvalAtMs: Date.now() - 3 * 60_000,
+  },
 };
 const plainJob = {
   ...baseJob,
@@ -90,6 +94,17 @@ suite.define(() => {
           .poll(async () => page.locator('[data-test-id="cron-row-plain-job"]').count())
           .toBe(0);
         expect(await conditionalRow.count()).toBe(1);
+
+        await conditionalRow.click();
+        await page.getByRole("tab", { name: "Run history", exact: true }).click();
+        const activity = page.locator('[data-test-id="cron-condition-activity"]');
+        await activity.waitFor();
+        await expect.poll(() => activity.textContent()).toContain("42");
+        await expect.poll(() => activity.textContent()).toContain("3m ago");
+        await expect.poll(() => activity.textContent()).toContain("Never");
+        await expect
+          .poll(() => page.locator(".cron-empty-state").textContent())
+          .toContain("No payload runs yet");
       },
     );
   });
diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts
index d083e4aab346..80d03301df7a 100644
--- a/ui/src/i18n/locales/en.ts
+++ b/ui/src/i18n/locales/en.ts
@@ -6422,6 +6422,20 @@ export const en: TranslationMap = {
       noMatching: "No matching runs.",
       emptyTitle: "No runs yet",
       emptyHint: "Runs show up here once an automation fires.",
+      conditionActivity: "Condition activity",
+      conditionActivityHint: "Checks run on schedule before the payload starts.",
+      checks: "Checks",
+      lastChecked: "Last checked",
+      lastFired: "Last fired",
+      notChecked: "Not checked yet",
+      neverFired: "Never",
+      emptyConditionTitle: "No payload runs yet",
+      emptyConditionHint:
+        "The condition has been checked {count} times without matching. Run history starts when the payload executes.",
+      emptyConditionHintOne:
+        "The condition has been checked once without matching. Run history starts when the payload executes.",
+      emptyConditionUnchecked:
+        "The condition has not been checked yet. Run history starts when the payload executes.",
       loadMore: "Load more runs",
       runStatusOk: "OK",
       runStatusError: "Error",
diff --git a/ui/src/pages/cron/view-runs.ts b/ui/src/pages/cron/view-runs.ts
index 70a2dd8fd436..ed8c46d073ae 100644
--- a/ui/src/pages/cron/view-runs.ts
+++ b/ui/src/pages/cron/view-runs.ts
@@ -37,6 +37,11 @@ type CronRunsSectionProps = {
   runsDeliveryStatuses: CronDeliveryStatus[];
   runsQuery: string;
   runsSortDir: CronSortDir;
+  conditionActivity?: {
+    checkCount: number;
+    lastCheckedAtMs?: number;
+    lastFiredAtMs?: number;
+  };
   onLoadMoreRuns: () => void;
   onRunsFiltersChange: (patch: {
     cronRunsStatuses?: CronRunsStatusValue[];
@@ -47,6 +52,49 @@ type CronRunsSectionProps = {
   onNavigateToChat?: (sessionKey: string) => void;
 };
 
+function renderConditionMetric(label: string, value: string) {
+  return html`
+    <div class="cron-condition-activity__metric">
+      <dt>${label}</dt>
+      <dd>${value}</dd>
+    </div>
+  `;
+}
+
+function renderConditionActivity(activity: NonNullable<CronRunsSectionProps["conditionActivity"]>) {
+  const lastChecked = formatRelativeTimestamp(activity.lastCheckedAtMs, {
+    fallback: t("cron.runs.notChecked"),
+  });
+  const lastFired = formatRelativeTimestamp(activity.lastFiredAtMs, {
+    fallback: t("cron.runs.neverFired"),
+  });
+  return html`
+    <div class="cron-condition-activity" data-test-id="cron-condition-activity">
+      <div class="cron-condition-activity__intro">
+        <div class="settings-row__title">
+          <span class="cron-condition-activity__icon" aria-hidden="true">${icon("gitBranch")}</span>
+          ${t("cron.runs.conditionActivity")}
+        </div>
+        <div class="settings-row__desc">${t("cron.runs.conditionActivityHint")}</div>
+      </div>
+      <dl class="cron-condition-activity__metrics">
+        ${renderConditionMetric(t("cron.runs.checks"), String(activity.checkCount))}
+        ${renderConditionMetric(t("cron.runs.lastChecked"), lastChecked)}
+        ${renderConditionMetric(t("cron.runs.lastFired"), lastFired)}
+      </dl>
+    </div>
+  `;
+}
+
+function conditionEmptyHint(activity: NonNullable<CronRunsSectionProps["conditionActivity"]>) {
+  if (activity.checkCount === 0) {
+    return t("cron.runs.emptyConditionUnchecked");
+  }
+  const key =
+    activity.checkCount === 1 ? "cron.runs.emptyConditionHintOne" : "cron.runs.emptyConditionHint";
+  return t(key, { count: String(activity.checkCount) });
+}
+
 function getRunStatusOptions(): Array<{ value: CronRunsStatusValue; label: string }> {
   return [
     { value: "ok", label: t("cron.runs.runStatusOk") },
@@ -179,6 +227,7 @@ export function renderRunsSection(props: CronRunsSectionProps) {
   // selected attributes preserve non-first values.
   return html`
     <div class="cron-runs">
+      ${props.conditionActivity ? renderConditionActivity(props.conditionActivity) : nothing}
       <div class="cron-run-filters">
         <div class="cron-search-box cron-run-filter-search">
           <span class="cron-search-box__icon" aria-hidden="true">${icon("search")}</span>
@@ -247,8 +296,16 @@ export function renderRunsSection(props: CronRunsSectionProps) {
           ? html`<div class="muted cron-runs__empty">${t("cron.runs.noMatching")}</div>`
           : html`
               <div class="cron-empty-state">
-                <div class="cron-empty-state__title">${t("cron.runs.emptyTitle")}</div>
-                <div class="cron-empty-state__copy">${t("cron.runs.emptyHint")}</div>
+                <div class="cron-empty-state__title">
+                  ${props.conditionActivity
+                    ? t("cron.runs.emptyConditionTitle")
+                    : t("cron.runs.emptyTitle")}
+                </div>
+                <div class="cron-empty-state__copy">
+                  ${props.conditionActivity
+                    ? conditionEmptyHint(props.conditionActivity)
+                    : t("cron.runs.emptyHint")}
+                </div>
               </div>
             `
         : html`
diff --git a/ui/src/pages/cron/view.ts b/ui/src/pages/cron/view.ts
index 972b76f661ac..d9702f0587c1 100644
--- a/ui/src/pages/cron/view.ts
+++ b/ui/src/pages/cron/view.ts
@@ -963,6 +963,13 @@ function renderDetailView(props: CronProps, mode: CronPanelMode) {
   const selectedJob = mode === "job" ? (props.editingJob ?? undefined) : undefined;
   const hasDetailTabs = mode === "job" && Boolean(selectedJob);
   const showHistory = mode === "job" && props.detailTab === "history";
+  const conditionActivity = selectedJob?.trigger
+    ? {
+        checkCount: selectedJob.state?.triggerEvalCount ?? 0,
+        lastCheckedAtMs: selectedJob.state?.lastTriggerEvalAtMs,
+        lastFiredAtMs: selectedJob.state?.lastTriggerFireAtMs,
+      }
+    : undefined;
   const children = [
     html`
       <div class="cron-back-row">
@@ -991,7 +998,9 @@ function renderDetailView(props: CronProps, mode: CronPanelMode) {
         ${showHistory
           ? renderSettingsSection(
               { title: t("cron.detail.historyTitle") },
-              html`<div class="cron-history">${renderRunsSection(props)}</div>`,
+              html`<div class="cron-history">
+                ${renderRunsSection({ ...props, conditionActivity })}
+              </div>`,
             )
           : renderEditor(props, mode)}
       </div>
diff --git a/ui/src/styles/cron.css b/ui/src/styles/cron.css
index 6295ae4e0ef6..c808cc0ac32b 100644
--- a/ui/src/styles/cron.css
+++ b/ui/src/styles/cron.css
@@ -859,6 +859,62 @@
   gap: var(--space-3);
 }
 
+.cron-condition-activity {
+  display: grid;
+  grid-template-columns: minmax(190px, 1.4fr) minmax(390px, 2fr);
+  align-items: center;
+  gap: var(--space-4);
+  padding-bottom: var(--space-3);
+  border-bottom: 1px solid color-mix(in srgb, var(--border) 60%, transparent);
+}
+
+.cron-condition-activity__intro {
+  min-width: 0;
+}
+
+.cron-condition-activity__intro .settings-row__title {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+}
+
+.cron-condition-activity__icon {
+  display: inline-flex;
+  color: var(--accent-2);
+}
+
+.cron-condition-activity__icon svg {
+  width: 13px;
+  height: 13px;
+  stroke: currentColor;
+  fill: none;
+}
+
+.cron-condition-activity__metrics {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  min-width: 0;
+  margin: 0;
+}
+
+.cron-condition-activity__metric {
+  min-width: 0;
+  padding-left: var(--space-4);
+  border-left: 1px solid var(--border);
+}
+
+.cron-condition-activity__metric dt {
+  color: var(--muted);
+  font-size: var(--control-ui-text-sm);
+}
+
+.cron-condition-activity__metric dd {
+  margin: 2px 0 0;
+  color: var(--text-strong);
+  font-size: 13px;
+  font-weight: 600;
+}
+
 .cron-run-filters {
   display: flex;
   align-items: center;
@@ -870,6 +926,17 @@
   flex: 1 1 220px;
 }
 
+@media (max-width: 768px) {
+  .cron-condition-activity {
+    grid-template-columns: 1fr;
+  }
+
+  .cron-condition-activity__metric:first-child {
+    padding-left: 0;
+    border-left: 0;
+  }
+}
+
 /* Match the .btn--sm dropdown triggers beside it instead of the native look. */
 .cron-run-sort {
   flex: 0 0 auto;

From f94f9453147f0d8109937439ae7c6403fa62fbd3 Mon Sep 17 00:00:00 2001
From: ClawSweeper <steipete+clawsweeper@gmail.com>
Date: Fri, 21 Aug 2026 06:56:43 -0700
Subject: [PATCH 004/124] improve(ui): declutter Automations across desktop and
 mobile (#127198)

* improve(ui): declutter automations list

* test: align automation UI and process cleanup

Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

---------

Co-authored-by: RoboClaw <309084314+roboclaw-bot@users.noreply.github.com>
Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>
---
 test/scripts/vitest-e2e-global-setup.test.ts |  13 +-
 ui/src/e2e/cron-descriptions.e2e.test.ts     |  12 +-
 ui/src/pages/cron/stats.ts                   |   8 +-
 ui/src/pages/cron/view-auto-disabled.test.ts |   9 +-
 ui/src/pages/cron/view-description.test.ts   |   2 +-
 ui/src/pages/cron/view-running-state.test.ts |   3 +
 ui/src/pages/cron/view.test.ts               |   4 +-
 ui/src/pages/cron/view.ts                    | 298 ++++++++++-------
 ui/src/styles/cron.css                       | 316 ++++++++++++++-----
 9 files changed, 446 insertions(+), 219 deletions(-)

diff --git a/test/scripts/vitest-e2e-global-setup.test.ts b/test/scripts/vitest-e2e-global-setup.test.ts
index b6fd8678bc53..afc3bf880c6c 100644
--- a/test/scripts/vitest-e2e-global-setup.test.ts
+++ b/test/scripts/vitest-e2e-global-setup.test.ts
@@ -7,12 +7,7 @@ import {
   forceKillVitestProcessGroup,
   forwardSignalToVitestProcessGroup,
 } from "../../scripts/vitest-process-group.mts";
-import {
-  isProcessAlive,
-  waitForChildClose,
-  waitForDead,
-  waitForPidFile,
-} from "../helpers/process-wait.js";
+import { waitForChildClose, waitForDead, waitForPidFile } from "../helpers/process-wait.js";
 import { runE2eGlobalSetup } from "../vitest/vitest.e2e.global-setup.js";
 
 type SetupCommandRunner = NonNullable<Parameters<typeof runE2eGlobalSetup>[0]>;
@@ -127,8 +122,12 @@ await runE2eSetupCommand([${JSON.stringify(fixturePath)}], process.env);`;
     } finally {
       forceKillVitestProcessGroup(runner);
       for (const pid of pids) {
-        if (isProcessAlive(pid)) {
+        try {
           process.kill(pid, "SIGKILL");
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== "ESRCH") {
+            throw error;
+          }
         }
       }
       fs.rmSync(fixtureDir, { force: true, recursive: true });
diff --git a/ui/src/e2e/cron-descriptions.e2e.test.ts b/ui/src/e2e/cron-descriptions.e2e.test.ts
index 912340ea1ced..41c527d8c7d1 100644
--- a/ui/src/e2e/cron-descriptions.e2e.test.ts
+++ b/ui/src/e2e/cron-descriptions.e2e.test.ts
@@ -24,7 +24,7 @@ function cronJob(id: string, name: string) {
 }
 
 suite.define(() => {
-  it("shows saved descriptions in compact rows and task details for every payload kind", async () => {
+  it("shows saved descriptions in list rows and task details for every payload kind", async () => {
     const jobs = [
       {
         ...cronJob("described-event", "System reminder"),
@@ -81,7 +81,7 @@ suite.define(() => {
 
         for (const job of jobs) {
           const description = page.locator(`[data-test-id="cron-row-description-${job.id}"]`);
-          expect((await description.textContent())?.trim()).toBe(`· ${job.description.trim()}`);
+          expect((await description.textContent())?.trim()).toBe(job.description.trim());
           expect(await description.getAttribute("title")).toBe(
             `Description: ${job.description.trim()}`,
           );
@@ -90,14 +90,6 @@ suite.define(() => {
           await page.locator(`[data-test-id="cron-row-description-${undescribedJob.id}"]`).count(),
         ).toBe(0);
 
-        const describedRow = await page
-          .locator(`[data-test-id="cron-row-${jobs[1].id}"]`)
-          .boundingBox();
-        const undescribedRow = await page
-          .locator(`[data-test-id="cron-row-${undescribedJob.id}"]`)
-          .boundingBox();
-        expect(describedRow?.height).toBe(undescribedRow?.height);
-
         for (const job of jobs) {
           const row = page.locator(`[data-test-id="cron-row-${job.id}"]`);
           await row.locator(".cron-table__name-text").click();
diff --git a/ui/src/pages/cron/stats.ts b/ui/src/pages/cron/stats.ts
index 36c8999f18f1..d8989fe360a5 100644
--- a/ui/src/pages/cron/stats.ts
+++ b/ui/src/pages/cron/stats.ts
@@ -1,6 +1,5 @@
 import { html } from "lit";
 import type { CronJob, CronStatus } from "../../api/types.ts";
-import { icon } from "../../components/icons.ts";
 import { t } from "../../i18n/index.ts";
 import { formatNextRun } from "../../lib/presenter.ts";
 
@@ -30,9 +29,10 @@ export function renderCronStats(props: {
   return html`
     <div class="cron-stats">
       <div class="cron-stat">
-        <span class="cron-stat__label">${t("cron.stats.tasks")}</span>
         <span class="cron-stat__value">${total}</span>
+        <span class="cron-stat__label">${t("cron.stats.tasks")}</span>
       </div>
+      <span class="cron-stat__separator" aria-hidden="true">·</span>
       <button
         type="button"
         class="cron-stat cron-stat--action"
@@ -44,7 +44,6 @@ export function renderCronStats(props: {
           void props.onRunsFiltersChange({ cronRunsStatuses: ["error"] });
         }}
       >
-        <span class="cron-stat__label">${t("cron.stats.failing")}</span>
         <span
           class="cron-stat__value ${typeof failing === "number" && failing > 0
             ? "cron-stat__value--danger"
@@ -52,8 +51,9 @@ export function renderCronStats(props: {
         >
           ${failing ?? t("common.na")}
         </span>
-        <span class="cron-stat__go" aria-hidden="true">${icon("chevronRight")}</span>
+        <span class="cron-stat__label">${t("cron.stats.failing")}</span>
       </button>
+      <span class="cron-stat__separator" aria-hidden="true">·</span>
       <div class="cron-stat">
         <span class="cron-stat__label">${t("cron.stats.nextWake")}</span>
         <span class="cron-stat__value cron-stat__value--time">
diff --git a/ui/src/pages/cron/view-auto-disabled.test.ts b/ui/src/pages/cron/view-auto-disabled.test.ts
index 2686c3d2f1c0..7a273fda7ca3 100644
--- a/ui/src/pages/cron/view-auto-disabled.test.ts
+++ b/ui/src/pages/cron/view-auto-disabled.test.ts
@@ -19,9 +19,14 @@ it("labels an auto-disabled job distinctly from an operator pause", () => {
   const container = renderView({ jobs: [paused, autoDisabled] });
   const rows = Array.from(container.querySelectorAll(".cron-table__row"));
   expect(rows[0]?.textContent).toContain("Paused");
+  expect(rows[0]?.querySelector(".cron-table__state--paused")?.getAttribute("aria-label")).toBe(
+    "Paused",
+  );
   const note = rows[1]?.querySelector("[data-test-id='cron-row-auto-disabled-job-auto']");
   expect(note?.textContent?.trim()).toBe("Auto-disabled · 10 run failures");
   expect(note?.getAttribute("title")).toBe("provider exploded");
-  // Escalated failure keeps the error dot even though the job is disabled.
-  expect(rows[1]?.querySelector(".cron-table__dot--error")).not.toBeNull();
+  // Escalated failure keeps a visible error marker even though the job is disabled.
+  expect(rows[1]?.querySelector(".cron-table__state--error")?.getAttribute("aria-label")).toBe(
+    "Auto-disabled · 10 run failures",
+  );
 });
diff --git a/ui/src/pages/cron/view-description.test.ts b/ui/src/pages/cron/view-description.test.ts
index e37943e22b05..e7fd1abd5461 100644
--- a/ui/src/pages/cron/view-description.test.ts
+++ b/ui/src/pages/cron/view-description.test.ts
@@ -26,7 +26,7 @@ describe("cron view saved descriptions", () => {
       );
 
       expect(description).toBeInstanceOf(HTMLSpanElement);
-      expect(description?.textContent?.trim()).toBe("· Summarize overnight deployment activity");
+      expect(description?.textContent?.trim()).toBe("Summarize overnight deployment activity");
       expect(description?.title).toBe("Description: Summarize overnight deployment activity");
       description?.click();
       expect(onSelectJob).toHaveBeenCalledWith(job);
diff --git a/ui/src/pages/cron/view-running-state.test.ts b/ui/src/pages/cron/view-running-state.test.ts
index 467fea2a735d..992dba08b188 100644
--- a/ui/src/pages/cron/view-running-state.test.ts
+++ b/ui/src/pages/cron/view-running-state.test.ts
@@ -13,5 +13,8 @@ it("shows Running instead of a past-due next-run time while a run executes", ()
   const container = renderView({ jobs: [running] });
   const row = container.querySelector(".cron-table__row");
   expect(row?.querySelector(".cron-table__running")?.textContent).toBe("Running");
+  expect(row?.querySelector(".cron-table__state--running")?.getAttribute("aria-label")).toBe(
+    "Running",
+  );
   expect(row?.textContent).not.toContain("ago");
 });
diff --git a/ui/src/pages/cron/view.test.ts b/ui/src/pages/cron/view.test.ts
index b79e2c425a72..fed8803ff32b 100644
--- a/ui/src/pages/cron/view.test.ts
+++ b/ui/src/pages/cron/view.test.ts
@@ -137,7 +137,9 @@ describe("cron view list pane", () => {
     expect(rows[0]?.textContent).toContain("Cron 0 9 * * *");
     expect(rows[1]?.classList.contains("cron-table__row--paused")).toBe(true);
     expect(rows[1]?.textContent).toContain("Paused");
-    expect(rows[2]?.querySelector(".cron-table__dot--error")).not.toBeNull();
+    expect(rows[2]?.querySelector(".cron-table__state--error")?.getAttribute("aria-label")).toBe(
+      "Error",
+    );
     expect(rows[2]?.querySelector(".cron-last-glyph--error")).not.toBeNull();
     expect(rows[2]?.querySelector(".cron-table__last-run")?.getAttribute("aria-label")).toBe(
       "Error",
diff --git a/ui/src/pages/cron/view.ts b/ui/src/pages/cron/view.ts
index d9702f0587c1..5f3cb7b80067 100644
--- a/ui/src/pages/cron/view.ts
+++ b/ui/src/pages/cron/view.ts
@@ -436,7 +436,10 @@ export function renderCron(props: CronProps) {
 function renderAdminRequired(props: CronProps) {
   return props.canManage
     ? nothing
-    : html`<div class="callout warning" role="note">${t("cron.adminRequired")}</div>`;
+    : html`<div class="cron-admin-note" role="note">
+        <span aria-hidden="true">${icon("lock")}</span>
+        <span>${t("cron.adminRequired")}</span>
+      </div>`;
 }
 
 // ── List view ──
@@ -474,17 +477,23 @@ function renderListView(props: CronProps) {
     !hasAnyJobsFilters &&
     props.canManage;
   const children = [
-    renderSettingsSection({}, renderCronStats(props)),
-    renderAdminRequired(props),
-    props.status && !props.status.enabled
-      ? html`
-          <div class="cron-error-banner" data-test-id="cron-scheduler-banner">
-            <strong>${t("cron.list.schedulerOff")}</strong> ${t("cron.runNotStarted.stopped")}
-          </div>
-        `
-      : nothing,
-    props.error ? html`<div class="cron-error-banner">${props.error}</div>` : nothing,
-    renderToolbar(props, hasAdvancedJobsFilters),
+    html`
+      <div class="cron-overview-header">
+        <div class="cron-overview-summary">
+          ${renderCronStats(props)} ${renderAdminRequired(props)}
+        </div>
+        ${props.status && !props.status.enabled
+          ? html`
+              <div class="cron-error-banner" data-test-id="cron-scheduler-banner">
+                <strong>${t("cron.list.schedulerOff")}</strong>
+                ${t("cron.runNotStarted.stopped")}
+              </div>
+            `
+          : nothing}
+        ${props.error ? html`<div class="cron-error-banner">${props.error}</div>` : nothing}
+        ${renderToolbar(props, hasAdvancedJobsFilters)}
+      </div>
+    `,
     html`
       <div
         id="cron-list-panel"
@@ -524,66 +533,71 @@ function renderListTabs(props: CronProps) {
   });
 }
 
-// One toolbar row for both list tabs: view switch left, tab filters middle, refresh + New right.
+// Navigation and primary actions stay stable above the task-only filter row.
 function renderToolbar(props: CronProps, hasAdvancedJobsFilters: boolean) {
   return html`
     <div class="cron-toolbar">
-      ${renderListTabs(props)}
+      <div class="cron-toolbar__primary">
+        ${renderListTabs(props)}
+        <div class="cron-toolbar__end">
+          <button
+            type="button"
+            class="btn btn--sm btn--ghost cron-refresh ${props.loading
+              ? "cron-refresh--loading"
+              : ""}"
+            ?disabled=${props.loading}
+            title=${props.loading ? t("cron.list.refreshing") : t("cron.list.refresh")}
+            aria-label=${t("cron.list.refresh")}
+            @click=${props.onRefresh}
+          >
+            ${icon("refresh")}
+          </button>
+          ${props.canManage
+            ? html`
+                <button
+                  type="button"
+                  class="btn primary btn--sm cron-new-task"
+                  data-test-id="cron-new-task"
+                  @click=${() => props.onOpenCreate()}
+                >
+                  ${icon("plus")} ${t("cron.list.newTask")}
+                </button>
+              `
+            : nothing}
+        </div>
+      </div>
       ${props.listTab === "tasks"
         ? html`
-            ${renderSegmented<CronJobsEnabledFilter>({
-              value: props.jobsEnabledFilter,
-              options: ENABLED_TABS.map((tab) => ({
-                value: tab.value,
-                label: t(tab.labelKey),
-                testId: `cron-tab-${tab.value}`,
-              })),
-              ariaLabel: t("cron.tabs.filterLabel"),
-              onChange: (value) => void props.onJobsFiltersChange({ cronJobsEnabledFilter: value }),
-            })}
-            <div class="cron-search-box">
-              <span class="cron-search-box__icon" aria-hidden="true">${icon("search")}</span>
-              <input
-                type="search"
-                class="settings-input"
-                .value=${props.jobsQuery}
-                aria-label=${t("cron.list.searchPlaceholder")}
-                placeholder=${t("cron.list.searchPlaceholder")}
-                @input=${(e: Event) =>
-                  props.onJobsFiltersChange({
-                    cronJobsQuery: (e.target as HTMLInputElement).value,
-                  })}
-              />
+            <div class="cron-toolbar__filters">
+              <div class="cron-search-box">
+                <span class="cron-search-box__icon" aria-hidden="true">${icon("search")}</span>
+                <input
+                  type="search"
+                  class="settings-input"
+                  .value=${props.jobsQuery}
+                  aria-label=${t("cron.list.searchPlaceholder")}
+                  placeholder=${t("cron.list.searchPlaceholder")}
+                  @input=${(e: Event) =>
+                    props.onJobsFiltersChange({
+                      cronJobsQuery: (e.target as HTMLInputElement).value,
+                    })}
+                />
+              </div>
+              ${renderSegmented<CronJobsEnabledFilter>({
+                value: props.jobsEnabledFilter,
+                options: ENABLED_TABS.map((tab) => ({
+                  value: tab.value,
+                  label: t(tab.labelKey),
+                  testId: `cron-tab-${tab.value}`,
+                })),
+                ariaLabel: t("cron.tabs.filterLabel"),
+                onChange: (value) =>
+                  void props.onJobsFiltersChange({ cronJobsEnabledFilter: value }),
+              })}
+              ${renderJobsFilterPopover(props, hasAdvancedJobsFilters)}
             </div>
-            ${renderJobsFilterPopover(props, hasAdvancedJobsFilters)}
           `
         : nothing}
-      <div class="cron-toolbar__end">
-        <button
-          type="button"
-          class="btn btn--sm btn--ghost cron-refresh ${props.loading
-            ? "cron-refresh--loading"
-            : ""}"
-          ?disabled=${props.loading}
-          title=${props.loading ? t("cron.list.refreshing") : t("cron.list.refresh")}
-          aria-label=${t("cron.list.refresh")}
-          @click=${props.onRefresh}
-        >
-          ${icon("refresh")}
-        </button>
-        ${props.canManage
-          ? html`
-              <button
-                type="button"
-                class="btn primary btn--sm cron-new-task"
-                data-test-id="cron-new-task"
-                @click=${() => props.onOpenCreate()}
-              >
-                ${icon("plus")} ${t("cron.list.newTask")}
-              </button>
-            `
-          : nothing}
-      </div>
     </div>
   `;
 }
@@ -713,13 +727,13 @@ function renderJobsFilterPopover(props: CronProps, active: boolean) {
 
 function renderJobsTable(props: CronProps, hasAnyJobsFilters: boolean) {
   return html`
-    <div class="cron-table">
+    <div class="cron-table ${props.canManage ? "" : "cron-table--read-only"}">
       <div class="cron-table__head" role="row">
         <span>${t("cron.jobs.name")}</span>
         <span>${t("cron.jobs.schedule")}</span>
         <span>${t("cron.jobs.nextRun")}</span>
         <span>${t("cron.jobs.lastRun")}</span>
-        <span aria-hidden="true"></span>
+        ${props.canManage ? html`<span aria-hidden="true"></span>` : nothing}
       </div>
       ${props.jobs.length === 0
         ? html`
@@ -753,11 +767,11 @@ function renderJobRow(job: CronJob, props: CronProps) {
   const description = job.description?.trim();
   const nextRunAtMs = job.state?.nextRunAtMs;
   const hasNextRun = typeof nextRunAtMs === "number" && Number.isFinite(nextRunAtMs);
-  const dotVariant = isCronJobActiveFailure(job)
-    ? "cron-table__dot--error"
-    : job.enabled
-      ? "cron-table__dot--active"
-      : "";
+  const nextRun = isCronJobRunning(job)
+    ? html`<span class="cron-table__running">${t("cron.runs.runStatusRunning")}</span>`
+    : hasNextRun
+      ? formatRelativeTimestamp(nextRunAtMs)
+      : t("common.na");
   return html`
     <div
       class="cron-table__row ${job.enabled ? "" : "cron-table__row--paused"}"
@@ -773,37 +787,44 @@ function renderJobRow(job: CronJob, props: CronProps) {
       }}
     >
       <span class="cron-table__name">
-        <span class="cron-table__dot ${dotVariant}" aria-hidden="true"></span>
-        <span class="cron-table__name-text">${job.name}</span>
-        ${description
-          ? html`
-              <span
-                class="cron-table__description"
-                data-test-id=${`cron-row-description-${job.id}`}
-                title=${`${t("cron.form.description")}: ${description}`}
-                >· ${description}</span
-              >
-            `
-          : nothing}
-        ${job.trigger ? renderTriggerIndicator() : nothing}
-        ${job.enabled ? nothing : renderDisabledNote(job)}
+        ${renderJobStateIndicator(job)}
+        <span class="cron-table__name-copy">
+          <span class="cron-table__name-line">
+            <span class="cron-table__name-text">${job.name}</span>
+            ${job.trigger ? renderTriggerIndicator() : nothing}
+          </span>
+          ${description || !job.enabled
+            ? html`
+                <span class="cron-table__name-meta">
+                  ${description
+                    ? html`
+                        <span
+                          class="cron-table__description"
+                          data-test-id=${`cron-row-description-${job.id}`}
+                          title=${`${t("cron.form.description")}: ${description}`}
+                          >${description}</span
+                        >
+                      `
+                    : nothing}
+                  ${description && !job.enabled
+                    ? html`<span class="cron-table__meta-separator" aria-hidden="true">·</span>`
+                    : nothing}
+                  ${job.enabled ? nothing : renderDisabledNote(job)}
+                </span>
+              `
+            : nothing}
+        </span>
       </span>
-      <span class="cron-table__cell">${formatCronSchedule(job)}</span>
-      <span class="cron-table__cell">
-        ${isCronJobRunning(job)
-          ? html`<span class="cron-table__running">${t("cron.runs.runStatusRunning")}</span>`
-          : hasNextRun
-            ? formatRelativeTimestamp(nextRunAtMs)
-            : t("common.na")}
-      </span>
-      <span class="cron-table__cell cron-table__last">${renderLastRunCell(job)}</span>
-      <span
-        class="cron-table__actions"
-        @click=${(e: Event) => e.stopPropagation()}
-        @keydown=${(e: Event) => e.stopPropagation()}
-      >
-        ${props.canManage
-          ? html`
+      ${renderJobCell("cron-table__schedule", t("cron.jobs.schedule"), formatCronSchedule(job))}
+      ${renderJobCell("cron-table__next", t("cron.jobs.nextRun"), nextRun)}
+      ${renderJobCell("cron-table__last", t("cron.jobs.lastRun"), renderLastRunCell(job))}
+      ${props.canManage
+        ? html`
+            <span
+              class="cron-table__actions"
+              @click=${(e: Event) => e.stopPropagation()}
+              @keydown=${(e: Event) => e.stopPropagation()}
+            >
               <button
                 type="button"
                 class="btn btn--sm btn--ghost cron-row-run"
@@ -820,13 +841,62 @@ function renderJobRow(job: CronJob, props: CronProps) {
                 testId: `cron-row-toggle-${job.id}`,
               })}
               ${renderJobMenu(props, job)}
-            `
-          : nothing}
-      </span>
+            </span>
+          `
+        : nothing}
     </div>
   `;
 }
 
+function renderJobCell(className: string, label: string, value: unknown) {
+  return html`<span class="cron-table__cell ${className}">
+    <span class="cron-table__cell-label">${label}</span>
+    <span class="cron-table__cell-value">${value}</span>
+  </span>`;
+}
+
+function renderJobStateIndicator(job: CronJob) {
+  const autoDisabled = job.state?.autoDisabled;
+  const state = isCronJobRunning(job)
+    ? {
+        className: "cron-table__state--running",
+        iconName: "loader" as const,
+        label: t("cron.runs.runStatusRunning"),
+      }
+    : autoDisabled
+      ? {
+          className: "cron-table__state--error",
+          iconName: "lock" as const,
+          label: disabledNoteLabel(job),
+        }
+      : isCronJobActiveFailure(job)
+        ? {
+            className: "cron-table__state--error",
+            iconName: "alertTriangle" as const,
+            label: t("cron.runs.runStatusError"),
+          }
+        : !job.enabled
+          ? {
+              className: "cron-table__state--paused",
+              iconName: "pause" as const,
+              label: t("cron.list.paused"),
+            }
+          : {
+              className: "cron-table__state--active",
+              iconName: null,
+              label: t("cron.detail.active"),
+            };
+  return html`<span
+    class="cron-table__state ${state.className}"
+    role="img"
+    aria-label=${state.label}
+    title=${state.label}
+    >${state.iconName
+      ? icon(state.iconName)
+      : html`<span class="cron-table__state-dot"></span>`}</span
+  >`;
+}
+
 function renderTriggerIndicator() {
   const label = t("cron.form.triggerConfigured");
   return html`<span class="cron-trigger-icon" role="img" aria-label=${label} title=${label}
@@ -842,12 +912,7 @@ function renderDisabledNote(job: CronJob) {
   if (!autoDisabled) {
     return html`<span class="muted cron-table__paused-note">${t("cron.list.paused")}</span>`;
   }
-  const label = t(
-    autoDisabled.reason === "schedule-errors"
-      ? "cron.list.autoDisabledScheduleErrors"
-      : "cron.list.autoDisabledRunFailures",
-    { count: String(autoDisabled.consecutiveErrors) },
-  );
+  const label = disabledNoteLabel(job);
   const lastError = job.state?.lastError?.trim();
   return html`<span
     class="cron-table__paused-note cron-table__auto-disabled"
@@ -857,6 +922,19 @@ function renderDisabledNote(job: CronJob) {
   >`;
 }
 
+function disabledNoteLabel(job: CronJob) {
+  const autoDisabled = job.state?.autoDisabled;
+  if (!autoDisabled) {
+    return t("cron.list.paused");
+  }
+  return t(
+    autoDisabled.reason === "schedule-errors"
+      ? "cron.list.autoDisabledScheduleErrors"
+      : "cron.list.autoDisabledRunFailures",
+    { count: String(autoDisabled.consecutiveErrors) },
+  );
+}
+
 function renderLastRunCell(job: CronJob) {
   const status = resolveCronJobLastRunStatus(job);
   const lastRunAtMs = job.state?.lastRunAtMs;
diff --git a/ui/src/styles/cron.css b/ui/src/styles/cron.css
index c808cc0ac32b..ab0d00741063 100644
--- a/ui/src/styles/cron.css
+++ b/ui/src/styles/cron.css
@@ -15,81 +15,72 @@
   overflow: visible;
 }
 
-/* ── Stat grid (escape hatch inside one group) ── */
+/* ── Compact overview chrome ── */
+
+.cron-page[data-panel-mode="overview"] .settings-page {
+  gap: var(--space-4);
+}
+
+.cron-overview-header {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+  min-width: 0;
+}
+
+.cron-overview-summary {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  min-width: 0;
+}
 
 .cron-stats {
-  display: grid;
-  grid-template-columns: repeat(3, minmax(0, 1fr));
-  gap: var(--space-4);
-  padding: var(--space-3) var(--space-4);
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-width: 0;
+  color: var(--muted);
+  font-size: var(--control-ui-text-sm);
 }
 
 .cron-stat {
   display: flex;
-  flex-direction: column;
-  gap: var(--space-2);
+  align-items: baseline;
+  gap: var(--space-1);
   min-width: 0;
 }
 
-/* Failing stat is a drill-down into run history filtered to errors. It sits
-   inside the stats group, so it is a bare button (no card chrome). */
+/* Failing is still a drill-down into run history, but reads as one fact in the
+   summary rather than a third competing card. */
 .cron-stat--action {
   position: relative;
-  text-align: left;
+  display: inline-flex;
+  align-items: baseline;
+  gap: var(--space-1);
   font: inherit;
   color: inherit;
   cursor: var(--cursor-action);
   border: 0;
   background: transparent;
-  margin: calc(-1 * var(--space-2));
-  padding: var(--space-2);
-  border-radius: var(--radius-md);
-  transition: background var(--duration-fast) var(--ease-out);
+  padding: 2px;
+  margin: -2px;
+  border-radius: var(--radius-sm);
+  transition: color var(--duration-fast) var(--ease-out);
 }
 
 .cron-stat--action:hover {
-  background: var(--bg-hover);
-}
-
-.cron-stat__go {
-  position: absolute;
-  top: 50%;
-  right: var(--space-3);
-  transform: translateY(-50%);
-  display: inline-flex;
-  color: var(--muted);
-  opacity: 0;
-  transition: opacity var(--duration-fast) var(--ease-out);
-}
-
-.cron-stat__go svg {
-  width: 14px;
-  height: 14px;
-  stroke: currentColor;
-  fill: none;
-}
-
-.cron-stat--action:hover .cron-stat__go,
-.cron-stat--action:focus-visible .cron-stat__go {
-  opacity: 1;
+  color: var(--text-strong);
 }
 
 .cron-stat__label {
-  color: var(--muted);
-  font-size: var(--control-ui-text-xs);
-  font-weight: 600;
-  text-transform: uppercase;
-  letter-spacing: 0.04em;
+  color: inherit;
 }
 
 .cron-stat__value {
   color: var(--text-strong);
-  font-size: 22px;
+  font-size: inherit;
   font-weight: 650;
-  line-height: 1.1;
-  min-height: 24px;
-  display: flex;
-  align-items: center;
 }
 
 .cron-stat__value--danger {
@@ -97,13 +88,29 @@
 }
 
 .cron-stat__value--time {
-  font-size: 14px;
   font-weight: 600;
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
-  display: block;
-  line-height: 24px;
+}
+
+.cron-stat__separator {
+  color: var(--border-strong);
+}
+
+.cron-admin-note {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+  min-width: 0;
+  margin-left: auto;
+  color: var(--muted);
+  font-size: var(--control-ui-text-xs);
+}
+
+.cron-admin-note svg {
+  width: 12px;
+  height: 12px;
 }
 
 /* Tab panel wrapping the tab-dependent sections; keeps the settings-page
@@ -111,17 +118,30 @@
 .cron-tab-panel {
   display: flex;
   flex-direction: column;
-  gap: var(--space-7);
+  gap: var(--space-4);
   min-width: 0;
 }
 
-/* ── One-row list toolbar (view switch, filters, refresh + New automation) ── */
+/* ── List toolbar ── */
 
 .cron-toolbar {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  min-width: 0;
+}
+
+.cron-toolbar__primary,
+.cron-toolbar__filters {
   display: flex;
   align-items: center;
   gap: var(--space-2);
-  flex-wrap: wrap;
+  width: 100%;
+  min-width: 0;
+}
+
+.cron-toolbar__primary {
+  border-bottom: 1px solid color-mix(in srgb, var(--border) 60%, transparent);
 }
 
 /* Toolbar buttons share the settings control height with the adjacent
@@ -134,9 +154,8 @@
 
 .cron-search-box {
   position: relative;
-  flex: 1 1 220px;
-  min-width: 180px;
-  max-width: 420px;
+  flex: 1 1 auto;
+  min-width: 0;
 }
 
 .cron-search-box__icon {
@@ -263,13 +282,20 @@
 
 /* ── Jobs table (escape hatch inside the tasks group) ── */
 
+.cron-table {
+  --cron-table-columns: minmax(220px, 1.8fr) minmax(160px, 1.05fr) minmax(110px, 0.7fr)
+    minmax(130px, 0.8fr) 116px;
+}
+
+.cron-table--read-only {
+  --cron-table-columns: minmax(220px, 1.8fr) minmax(160px, 1.05fr) minmax(110px, 0.7fr)
+    minmax(130px, 0.8fr);
+}
+
 .cron-table__head,
 .cron-table__row {
   display: grid;
-  grid-template-columns: minmax(180px, 1.6fr) minmax(150px, 1.1fr) minmax(110px, 0.8fr) minmax(
-      140px,
-      0.9fr
-    ) 116px;
+  grid-template-columns: var(--cron-table-columns);
   gap: var(--space-3);
   align-items: center;
   padding: 0 var(--space-4);
@@ -309,7 +335,7 @@
 
 .cron-table__name {
   display: flex;
-  align-items: center;
+  align-items: flex-start;
   gap: 10px;
   min-width: 0;
   color: var(--text-strong);
@@ -317,33 +343,84 @@
   font-weight: 600;
 }
 
-.cron-table__dot {
+.cron-table__state {
   flex: 0 0 auto;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 14px;
+  height: 14px;
+  margin-top: 2px;
+  color: var(--muted);
+}
+
+.cron-table__state svg {
+  width: 13px;
+  height: 13px;
+  stroke: currentColor;
+  fill: none;
+}
+
+.cron-table__state-dot {
   width: 8px;
   height: 8px;
   border-radius: 999px;
-  background: var(--muted);
-  opacity: 0.5;
-}
-
-.cron-table__dot--active {
   background: var(--ok);
-  opacity: 1;
 }
 
-.cron-table__dot--error {
-  background: var(--danger);
-  opacity: 1;
+.cron-table__state--running {
+  color: var(--accent-2);
+}
+
+.cron-table__state--running svg {
+  animation: cron-state-spin 1s linear infinite;
+}
+
+.cron-table__state--error {
+  color: var(--danger);
+}
+
+.cron-table__state--paused {
+  color: var(--muted);
+}
+
+@keyframes cron-state-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .cron-table__state--running svg {
+    animation: none;
+  }
+}
+
+.cron-table__name-copy {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+  flex: 1 1 auto;
+}
+
+.cron-table__name-line,
+.cron-table__name-meta {
+  display: flex;
+  align-items: center;
+  gap: var(--space-1);
+  min-width: 0;
 }
 
 .cron-table__name-text {
+  min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
 .cron-table__description {
-  flex: 1 1 0;
+  flex: 0 1 auto;
   min-width: 0;
   overflow: hidden;
   color: var(--muted);
@@ -358,8 +435,12 @@
   font-size: var(--control-ui-text-xs);
 }
 
+.cron-table__meta-separator {
+  color: var(--muted);
+}
+
 .cron-table__running {
-  color: var(--accent);
+  color: var(--accent-2);
 }
 
 .cron-table__auto-disabled {
@@ -375,6 +456,17 @@
   white-space: nowrap;
 }
 
+.cron-table__cell-label {
+  display: none;
+}
+
+.cron-table__cell-value {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 .cron-table__last {
   display: flex;
   align-items: center;
@@ -1107,41 +1199,97 @@
 /* ── Responsive ── */
 
 @media (max-width: 900px) {
-  /* Stack table rows into label-free cards; hide the head and secondary cells. */
+  /* Keep every table fact, but label and arrange it as a compact card. */
   .cron-table__head {
     display: none;
   }
 
   .cron-table__row {
-    grid-template-columns: minmax(0, 1fr) 116px;
-    row-gap: 4px;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: var(--space-2) var(--space-3);
+    padding-top: var(--space-3);
+    padding-bottom: var(--space-3);
   }
 
   .cron-table__name {
-    grid-column: 1;
+    grid-column: 1 / -1;
   }
 
-  .cron-table__actions {
-    grid-column: 2;
-    grid-row: 1;
+  .cron-table__schedule {
+    grid-column: 1 / -1;
   }
 
   .cron-table__cell {
-    grid-column: 1;
+    display: flex;
+    align-items: baseline;
+    gap: var(--space-1);
     color: var(--muted);
     font-size: var(--control-ui-text-sm);
+    white-space: normal;
+  }
+
+  .cron-table__cell-label {
+    display: inline;
+    flex: 0 0 auto;
+    color: var(--muted);
+    font-size: var(--control-ui-text-xs);
+    font-weight: 600;
+  }
+
+  .cron-table__cell-label::after {
+    content: ":";
+  }
+
+  .cron-table__cell-value {
+    white-space: normal;
+    overflow-wrap: anywhere;
+  }
+
+  .cron-table__actions {
+    grid-column: 1 / -1;
+    justify-content: flex-start;
+    padding-left: 24px;
   }
 }
 
 @media (max-width: 560px) {
   .cron-stats {
-    grid-template-columns: 1fr;
+    flex-wrap: wrap;
+  }
+
+  .cron-overview-summary {
+    align-items: flex-start;
+    flex-direction: column;
+    gap: var(--space-2);
+  }
+
+  .cron-admin-note {
+    margin-left: 0;
+  }
+
+  .cron-toolbar__filters {
+    flex-wrap: wrap;
   }
 
   .cron-search-box {
-    max-width: none;
     flex-basis: 100%;
   }
+
+  .cron-filter-popover__trigger {
+    margin-left: auto;
+  }
+
+  .cron-new-task {
+    width: 32px;
+    padding: 0;
+    justify-content: center;
+    font-size: 0;
+  }
+
+  .cron-new-task svg {
+    width: 14px;
+    height: 14px;
+  }
 }
 
 /* Web Awesome popup surfaces own positioning, dismissal, and focus. */

From ff83e3efe811d561aee0e8d7cd38047294b1cb58 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yi=C4=9Fit=20ERDO=C4=9EAN?= <yigiterdogan023@gmail.com>
Date: Fri, 21 Aug 2026 17:22:57 +0300
Subject: [PATCH 005/124] test(extensions): close cached agent databases before
 removing fixture state dirs (#126352)

Doctor migrations and auth-profile writes open per-agent and shared state
databases under the fixture's temporary directory. Clearing the plugin
state store or the runtime auth snapshots does not release those handles,
so Windows fails the directory removal with EBUSY while Linux unlinks the
open files and stays green.

Close the cached databases before each removal, matching the ordering the
zalouser and zalo fixtures already use.
---
 extensions/acpx/doctor-contract-api.test.ts   |  1 +
 .../active-memory/doctor-contract-api.test.ts |  1 +
 .../alibaba/video-generation-provider.test.ts |  5 ++
 extensions/codex/doctor-contract-api.test.ts  | 61 +++++++++++--------
 .../device-pair/doctor-contract-api.test.ts   |  1 +
 .../memory-core/doctor-contract-api.test.ts   |  1 +
 .../msteams/doctor-contract-api.test.ts       |  1 +
 .../openai/video-generation-provider.test.ts  |  5 ++
 8 files changed, 49 insertions(+), 27 deletions(-)

diff --git a/extensions/acpx/doctor-contract-api.test.ts b/extensions/acpx/doctor-contract-api.test.ts
index bfa404bddad5..ad9263fe7617 100644
--- a/extensions/acpx/doctor-contract-api.test.ts
+++ b/extensions/acpx/doctor-contract-api.test.ts
@@ -105,6 +105,7 @@ describe("acpx doctor state migration", () => {
   });
 
   afterEach(async () => {
+    resetPluginStateStoreForTests();
     await fs.rm(stateDir, { recursive: true, force: true });
   });
 
diff --git a/extensions/active-memory/doctor-contract-api.test.ts b/extensions/active-memory/doctor-contract-api.test.ts
index b0716b7ef474..0fc3e640bde1 100644
--- a/extensions/active-memory/doctor-contract-api.test.ts
+++ b/extensions/active-memory/doctor-contract-api.test.ts
@@ -65,6 +65,7 @@ describe("active-memory doctor state migration", () => {
 
   afterEach(async () => {
     vi.useRealTimers();
+    resetPluginStateStoreForTests();
     await fs.rm(stateDir, { recursive: true, force: true });
   });
 
diff --git a/extensions/alibaba/video-generation-provider.test.ts b/extensions/alibaba/video-generation-provider.test.ts
index 3a0dfbbba0b0..56e44a4717d4 100644
--- a/extensions/alibaba/video-generation-provider.test.ts
+++ b/extensions/alibaba/video-generation-provider.test.ts
@@ -22,6 +22,7 @@ import {
   mockSuccessfulDashscopeVideoTask,
 } from "openclaw/plugin-sdk/provider-test-contracts";
 // Alibaba tests cover video generation provider plugin behavior.
+import { closeOpenClawAgentDatabasesForTest } from "openclaw/plugin-sdk/sqlite-runtime-testing";
 import { createRequireRecord } from "openclaw/plugin-sdk/test-fixtures";
 import {
   DASHSCOPE_WAN_VIDEO_MODELS,
@@ -276,6 +277,10 @@ describe("alibaba video generation provider", () => {
       expect(alibabaVideoGenerationProvider.isConfigured?.({ cfg: {}, agentDir })).toBe(expected);
     } finally {
       clearRuntimeAuthProfileStoreSnapshots();
+      // Saving the profile store opens the per-agent database under the temporary agent
+      // dir, and clearing the snapshots does not release it, so Windows fails the removal
+      // with EBUSY unless the cached handles are closed first.
+      closeOpenClawAgentDatabasesForTest();
       await fs.rm(agentDir, { force: true, recursive: true });
     }
   });
diff --git a/extensions/codex/doctor-contract-api.test.ts b/extensions/codex/doctor-contract-api.test.ts
index f022791762ba..e1411564c755 100644
--- a/extensions/codex/doctor-contract-api.test.ts
+++ b/extensions/codex/doctor-contract-api.test.ts
@@ -11,6 +11,7 @@ import type {
   PluginDoctorStateMigrationContext,
 } from "openclaw/plugin-sdk/runtime-doctor-migrations";
 import { getSessionEntry, upsertSessionEntry } from "openclaw/plugin-sdk/session-store-runtime";
+import { closeOpenClawAgentDatabasesForTest } from "openclaw/plugin-sdk/sqlite-runtime-testing";
 import { afterEach, describe, expect, it } from "vitest";
 import {
   legacyConfigRules,
@@ -59,6 +60,16 @@ function openBindingStore(env: NodeJS.ProcessEnv) {
   });
 }
 
+async function removeCodexDoctorFixture(stateDir: string): Promise<void> {
+  // Doctor migrations open per-agent databases and leave the shared state database open under
+  // the temporary state dir; both must be released before removal or Windows keeps the files
+  // locked and the removal fails with EBUSY. Agent close first: it releases leases through
+  // shared state, so the reverse order can reopen it.
+  closeOpenClawAgentDatabasesForTest();
+  resetPluginStateStoreForTests();
+  await fs.rm(stateDir, { recursive: true, force: true });
+}
+
 async function createBindingMigrationFixture(options: {
   binding?: Record<string, unknown>;
   legacySharedRoot?: boolean;
@@ -272,7 +283,7 @@ describe("codex doctor contract", () => {
         }),
       ).toMatchObject({ agentHarnessId: "codex" });
     } finally {
-      await fs.rm(fixture.stateDir, { recursive: true, force: true });
+      await removeCodexDoctorFixture(fixture.stateDir);
     }
   });
 
@@ -357,7 +368,7 @@ describe("codex doctor contract", () => {
       fs.readFile(fixture.storePath, "utf8").then(JSON.parse),
     ).resolves.not.toHaveProperty("agent:main:session-1.agentHarnessId");
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it.each([
@@ -396,7 +407,7 @@ describe("codex doctor contract", () => {
     await expect(fs.access(`${fixture.sidecarPath}.migrated`)).rejects.toThrow();
     await expect(openBindingStore(fixture.env).entries()).resolves.toEqual([]);
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it("migrates a shared-root binding to the configured system agent", async () => {
@@ -448,7 +459,7 @@ describe("codex doctor contract", () => {
     ).toMatchObject({ agentHarnessId: "codex" });
     await expect(fs.access(`${fixture.sidecarPath}.migrated`)).resolves.toBeUndefined();
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it("keeps an agent-scoped shared-root binding with its explicit owner", async () => {
@@ -492,7 +503,7 @@ describe("codex doctor contract", () => {
     ).resolves.toMatchObject({ sessionId: "explicit-ops-owner" });
     await expect(fs.access(`${fixture.sidecarPath}.migrated`)).resolves.toBeUndefined();
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it("bounds oversized legacy fingerprints before plugin-state import", async () => {
@@ -560,7 +571,7 @@ describe("codex doctor contract", () => {
       warnings: [],
     });
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it("normalizes a partial raw conversation import before copying the session row", async () => {
@@ -638,7 +649,7 @@ describe("codex doctor contract", () => {
       warnings: [],
     });
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it("normalizes retained raw conversation and session rows before comparison", async () => {
@@ -710,7 +721,7 @@ describe("codex doctor contract", () => {
       warnings: [],
     });
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it("rejects an explicit session file locator outside the session directory", async () => {
@@ -743,7 +754,7 @@ describe("codex doctor contract", () => {
     ).toBeUndefined();
     await expect(openBindingStore(fixture.env).entries()).resolves.toEqual([]);
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it("deduplicates session-store aliases before classifying binding ownership", async () => {
@@ -795,7 +806,7 @@ describe("codex doctor contract", () => {
     expect(configuredIndex["agent:main:aliased-store"]).not.toHaveProperty("agentHarnessId");
     expect(targetIndex["agent:main:aliased-store"]).not.toHaveProperty("agentHarnessId");
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it("resolves relative session files from a symlinked store path", async () => {
@@ -847,7 +858,7 @@ describe("codex doctor contract", () => {
       `${sessionKey}.agentHarnessId`,
     );
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it.each([
@@ -929,7 +940,7 @@ describe("codex doctor contract", () => {
         retired: true,
       });
 
-      await fs.rm(fixture.stateDir, { recursive: true, force: true });
+      await removeCodexDoctorFixture(fixture.stateDir);
     },
   );
 
@@ -986,7 +997,7 @@ describe("codex doctor contract", () => {
       retired: true,
     });
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it("does not resurrect a retired session generation from its legacy sidecar", async () => {
@@ -1041,7 +1052,7 @@ describe("codex doctor contract", () => {
       fs.readFile(path.join(fixture.sessionsDir, "sessions.json"), "utf8").then(JSON.parse),
     ).resolves.not.toHaveProperty(`${sessionKey}.agentHarnessId`);
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it.each(["active", "cleared"] as const)(
@@ -1081,7 +1092,7 @@ describe("codex doctor contract", () => {
         warnings: [],
       });
 
-      await fs.rm(fixture.stateDir, { recursive: true, force: true });
+      await removeCodexDoctorFixture(fixture.stateDir);
     },
   );
 
@@ -1106,7 +1117,7 @@ describe("codex doctor contract", () => {
     await expect(fs.access(fixture.sidecarPath)).rejects.toThrow();
     await expect(fs.access(`${fixture.sidecarPath}.migrated`)).resolves.toBeUndefined();
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it("retains a zero-owner sidecar when canonical plugin state is malformed", async () => {
@@ -1135,7 +1146,7 @@ describe("codex doctor contract", () => {
     await expect(fs.access(fixture.sidecarPath)).resolves.toBeUndefined();
     await expect(store.lookup(bindingKey)).resolves.toEqual(malformed);
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it("retains mixed Codex and foreign ambiguous binding owners", async () => {
@@ -1164,7 +1175,7 @@ describe("codex doctor contract", () => {
     await expect(fs.access(fixture.sidecarPath)).resolves.toBeUndefined();
     await expect(openBindingStore(fixture.env).entries()).resolves.toEqual([]);
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it("retains a sidecar owned by a foreign harness without importing plugin state", async () => {
@@ -1188,7 +1199,7 @@ describe("codex doctor contract", () => {
     await expect(fs.access(fixture.sidecarPath)).resolves.toBeUndefined();
     await expect(openBindingStore(fixture.env).entries()).resolves.toEqual([]);
 
-    await fs.rm(fixture.stateDir, { recursive: true, force: true });
+    await removeCodexDoctorFixture(fixture.stateDir);
   });
 
   it.each([
@@ -1230,10 +1241,8 @@ describe("codex doctor contract", () => {
     await expect(fs.access(`${fixture.sidecarPath}.migrated`)).rejects.toThrow();
     await expect(openBindingStore(fixture.env).entries()).resolves.toEqual([]);
 
-    await Promise.all([
-      fs.rm(fixture.stateDir, { recursive: true, force: true }),
-      fs.rm(externalDir, { recursive: true, force: true }),
-    ]);
+    await removeCodexDoctorFixture(fixture.stateDir);
+    await fs.rm(externalDir, { recursive: true, force: true });
   });
 
   it("does not scan above stateDir or follow escaped external store locators", async () => {
@@ -1284,10 +1293,8 @@ describe("codex doctor contract", () => {
 
     await expect(migration.detectLegacyState(params)).resolves.toBeNull();
 
-    await Promise.all([
-      fs.rm(outerDir, { recursive: true, force: true }),
-      fs.rm(outsideDir, { recursive: true, force: true }),
-    ]);
+    await removeCodexDoctorFixture(outerDir);
+    await fs.rm(outsideDir, { recursive: true, force: true });
   });
 
   it("renames old approval-routed destructive plugin policy values", () => {
diff --git a/extensions/device-pair/doctor-contract-api.test.ts b/extensions/device-pair/doctor-contract-api.test.ts
index 2b3a92dccfe0..919f5c9b0e5f 100644
--- a/extensions/device-pair/doctor-contract-api.test.ts
+++ b/extensions/device-pair/doctor-contract-api.test.ts
@@ -43,6 +43,7 @@ describe("device-pair doctor notify migration", () => {
   });
 
   afterEach(async () => {
+    resetPluginStateStoreForTests();
     await fs.rm(stateDir, { recursive: true, force: true });
   });
 
diff --git a/extensions/memory-core/doctor-contract-api.test.ts b/extensions/memory-core/doctor-contract-api.test.ts
index 90d08a55a737..38e45c064bf6 100644
--- a/extensions/memory-core/doctor-contract-api.test.ts
+++ b/extensions/memory-core/doctor-contract-api.test.ts
@@ -488,6 +488,7 @@ describe("memory-core doctor dreaming migration", () => {
 
   afterEach(async () => {
     resetMemoryCoreDreamingStateForTests();
+    resetPluginStateStoreForTests();
     await fs.rm(rootDir, { recursive: true, force: true });
   });
 
diff --git a/extensions/msteams/doctor-contract-api.test.ts b/extensions/msteams/doctor-contract-api.test.ts
index 0c66fde14c69..9d19d44418eb 100644
--- a/extensions/msteams/doctor-contract-api.test.ts
+++ b/extensions/msteams/doctor-contract-api.test.ts
@@ -83,6 +83,7 @@ describe("msteams doctor state migration", () => {
   });
 
   afterEach(async () => {
+    resetPluginStateStoreForTests();
     await fs.rm(stateDir, { recursive: true, force: true });
   });
 
diff --git a/extensions/openai/video-generation-provider.test.ts b/extensions/openai/video-generation-provider.test.ts
index d50989b5cbcc..a09f37cb051b 100644
--- a/extensions/openai/video-generation-provider.test.ts
+++ b/extensions/openai/video-generation-provider.test.ts
@@ -13,6 +13,7 @@ import {
   installProviderHttpMockCleanup,
 } from "openclaw/plugin-sdk/provider-http-test-mocks";
 import { expectExplicitVideoGenerationCapabilities } from "openclaw/plugin-sdk/provider-test-contracts";
+import { closeOpenClawAgentDatabasesForTest } from "openclaw/plugin-sdk/sqlite-runtime-testing";
 import { beforeAll, describe, expect, it, vi } from "vitest";
 
 const {
@@ -171,6 +172,10 @@ describe("openai video generation provider", () => {
       } else {
         process.env.OPENAI_API_KEY = previousOpenAIKey;
       }
+      // Saving the profile store opens the per-agent database under the temporary agent
+      // dir, and clearing the snapshots does not release it, so Windows fails the removal
+      // with EBUSY unless the cached handles are closed first.
+      closeOpenClawAgentDatabasesForTest();
       fs.rmSync(agentDir, { recursive: true, force: true });
     }
   });

From 2cbfade48b617ef5dea7e8ef47737959d0918009 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 07:31:58 -0700
Subject: [PATCH 006/124] fix(ui): copy task results through clipboard fallback
 (#127181)

Amp-Thread-ID: https://ampcode.com/threads/T-01a021f4-b547-7788-a916-d4a94cbd3e3b

Co-authored-by: Amp <amp@ampcode.com>
---
 ui/src/lib/clipboard.test.ts          |  21 +++
 ui/src/lib/clipboard.ts               |  10 +-
 ui/src/pages/tasks/tasks-page.test.ts |  46 ++++++
 ui/src/pages/tasks/tasks-page.ts      |  27 +++-
 ui/src/pages/tasks/tasks.e2e.test.ts  | 225 +++++++++++++++++++++++++-
 ui/src/pages/tasks/view.ts            |   6 +-
 6 files changed, 320 insertions(+), 15 deletions(-)

diff --git a/ui/src/lib/clipboard.test.ts b/ui/src/lib/clipboard.test.ts
index e3424ae2ff75..82bacd9b4c76 100644
--- a/ui/src/lib/clipboard.test.ts
+++ b/ui/src/lib/clipboard.test.ts
@@ -46,6 +46,27 @@ describe("copyToClipboard", () => {
     expect(document.querySelector("textarea")).toBeNull();
   });
 
+  it("skips fallback when the caller retires a rejected async write", async () => {
+    let rejectWrite: ((reason?: unknown) => void) | undefined;
+    const writeText = vi.fn().mockImplementation(
+      () =>
+        new Promise<void>((_resolve, reject) => {
+          rejectWrite = reject;
+        }),
+    );
+    vi.stubGlobal("navigator", { clipboard: { writeText } });
+    const exec = mockExecCommand(true);
+    let current = true;
+
+    const copy = copyToClipboard("hello", () => current);
+    current = false;
+    rejectWrite?.(new Error("denied"));
+
+    expect(await copy).toBe(false);
+    expect(exec).not.toHaveBeenCalled();
+    expect(document.querySelector("textarea")).toBeNull();
+  });
+
   it("falls back to execCommand over plain HTTP where navigator.clipboard is undefined", async () => {
     vi.stubGlobal("navigator", {});
     const exec = mockExecCommand(true);
diff --git a/ui/src/lib/clipboard.ts b/ui/src/lib/clipboard.ts
index 57784c85c6c3..8e2a2b983979 100644
--- a/ui/src/lib/clipboard.ts
+++ b/ui/src/lib/clipboard.ts
@@ -5,7 +5,10 @@
 // is undefined, so calling it throws synchronously rather than rejecting. Guard
 // the secure-context path and fall back to the legacy execCommand copy so the
 // copy buttons keep working over HTTP. Returns whether the copy succeeded.
-export async function copyToClipboard(text: string): Promise<boolean> {
+export async function copyToClipboard(
+  text: string,
+  shouldFallback?: () => boolean,
+): Promise<boolean> {
   if (!text) {
     return false;
   }
@@ -18,6 +21,11 @@ export async function copyToClipboard(text: string): Promise<boolean> {
       // fall through to the execCommand path before giving up.
     }
   }
+  // A rejected async write can settle after newer caller-owned work. Let that
+  // owner retire this second transport attempt before it mutates the clipboard.
+  if (shouldFallback && !shouldFallback()) {
+    return false;
+  }
   return copyWithExecCommand(text);
 }
 
diff --git a/ui/src/pages/tasks/tasks-page.test.ts b/ui/src/pages/tasks/tasks-page.test.ts
index 3054dd085365..9d1f626df0a7 100644
--- a/ui/src/pages/tasks/tasks-page.test.ts
+++ b/ui/src/pages/tasks/tasks-page.test.ts
@@ -10,8 +10,10 @@ type TasksPageTestElement = HTMLElement & {
   context: ApplicationContext;
   tasks: TaskSummary[];
   error: string | null;
+  copyResultError: string | null;
   cancellingTaskIds: Set<string>;
   cancelTask: (taskId: string) => Promise<void>;
+  copyTaskResult: (taskId: string) => Promise<void>;
   recoverTask: (taskId: string, action: "retry" | "dismiss") => Promise<void>;
   refreshTasks: () => Promise<void>;
 };
@@ -162,6 +164,7 @@ function createContext(
 afterEach(() => {
   document.body.replaceChildren();
   vi.restoreAllMocks();
+  vi.unstubAllGlobals();
 });
 
 describe("TasksPage concurrent refresh events", () => {
@@ -447,6 +450,49 @@ describe("TasksPage active pagination", () => {
 });
 
 describe("TasksPage cancellation lifecycle", () => {
+  it("does not clear an unrelated task error when a result copy succeeds", async () => {
+    const blocked = createTask("task-copy-independent-error", "completed", {
+      deliveryStatus: "failed",
+      terminalOutcome: "blocked",
+    });
+    const clipboardWrite = deferred<void>();
+    const writeText = vi.fn(() => clipboardWrite.promise);
+    const request = vi.fn((method: string) => {
+      if (method === "tasks.get") {
+        return Promise.resolve({ task: { ...blocked, result: "Retained result" } });
+      }
+      if (method === "tasks.retry") {
+        return Promise.resolve({
+          results: [
+            {
+              taskId: blocked.taskId,
+              ok: false,
+              reason: "Independent recovery failed",
+            },
+          ],
+        });
+      }
+      return Promise.resolve({ tasks: [blocked] });
+    });
+    const source = createGateway({ request } as unknown as GatewayBrowserClient);
+    const page = document.createElement("openclaw-tasks-page") as TasksPageTestElement;
+    page.context = createContext(source.gateway);
+    document.body.append(page);
+    await waitForFast(() => expect(page.tasks).toHaveLength(1));
+    vi.stubGlobal("navigator", { clipboard: { writeText } });
+
+    const copying = page.copyTaskResult(blocked.taskId);
+    await vi.waitFor(() => expect(writeText).toHaveBeenCalledWith("Retained result"));
+    await page.recoverTask(blocked.taskId, "retry");
+    expect(page.error).toBe("Independent recovery failed");
+
+    clipboardWrite.resolve(undefined);
+    await copying;
+
+    expect(page.error).toBe("Independent recovery failed");
+    expect(page.copyResultError).toBeNull();
+  });
+
   it("lets a read-only operator copy a retained result without mutation controls", async () => {
     const retained = createTask("task-read-only-retained", "completed", {
       deliveryStatus: "failed",
diff --git a/ui/src/pages/tasks/tasks-page.ts b/ui/src/pages/tasks/tasks-page.ts
index 8b9ead6fd442..d60377df8f22 100644
--- a/ui/src/pages/tasks/tasks-page.ts
+++ b/ui/src/pages/tasks/tasks-page.ts
@@ -9,6 +9,7 @@ import { hasOperatorReadAccess, hasOperatorWriteAccess } from "../../app/operato
 import { renderAgentScopeControl } from "../../components/agent-scope-control.ts";
 import { t } from "../../i18n/index.ts";
 import { watchAgentScope } from "../../lib/agents/index.ts";
+import { copyToClipboard } from "../../lib/clipboard.ts";
 import { formatUiError, formatUiExternalText } from "../../lib/format-error.ts";
 import {
   findUiSessionRow,
@@ -99,14 +100,17 @@ class TasksPage extends OpenClawLightDomElement {
 
   @state() private tasks: TaskSummary[] = [];
   @state() private error: string | null = null;
+  @state() private copyResultError: string | null = null;
   @state() private cancellingTaskIds = new Set<string>();
 
   private taskRefreshEvents: TaskRefreshEventBuffer | null = null;
+  private copyResultAttempt = 0;
   private readonly gateway = new GatewayPageController(this, {
     getGateway: () => this.context?.gateway,
     onIdentityChange: () => {
       this.tasks = [];
       this.error = null;
+      this.copyResultError = null;
     },
     invalidateRequests: () => this.cancelGatewayWork(),
     onSnapshot: () => {
@@ -238,6 +242,8 @@ class TasksPage extends OpenClawLightDomElement {
     );
 
   override disconnectedCallback() {
+    this.copyResultAttempt += 1;
+    this.copyResultError = null;
     this.subscriptions.clear();
     super.disconnectedCallback();
   }
@@ -245,6 +251,8 @@ class TasksPage extends OpenClawLightDomElement {
   private cancelGatewayWork() {
     // Reconnects may reuse the client object; the epoch keeps pre-disconnect
     // cancellation responses from mutating the replacement task snapshot.
+    this.copyResultAttempt += 1;
+    this.copyResultError = null;
     this.taskRefreshEvents = null;
     void this.listTask.run([null, null, null]);
     this.cancellingTaskIds = new Set();
@@ -258,6 +266,7 @@ class TasksPage extends OpenClawLightDomElement {
     }
     const scopeId = this.context.agentSelection.state.scopeId;
     this.error = null;
+    this.copyResultError = null;
     return this.listTask.run([gateway, client, scopeId]);
   }
 
@@ -353,6 +362,7 @@ class TasksPage extends OpenClawLightDomElement {
   }
 
   private async copyTaskResult(taskId: string) {
+    const attempt = ++this.copyResultAttempt;
     const scope = this.gateway.capture();
     const gateway = this.gateway.gateway;
     if (!scope || !gateway || this.context.gateway !== gateway) {
@@ -360,18 +370,24 @@ class TasksPage extends OpenClawLightDomElement {
     }
     try {
       const detail = normalizeTasksGetResult(await scope.client.request("tasks.get", { taskId }));
-      if (!this.gateway.isCurrent(scope)) {
+      if (!this.gateway.isCurrent(scope) || attempt !== this.copyResultAttempt) {
         return;
       }
       const result = detail?.result ?? detail?.progressSummary;
       if (!result) {
-        this.error = t("tasksPage.recoveryFailed");
+        this.copyResultError = t("tasksPage.recoveryFailed");
         return;
       }
-      await navigator.clipboard.writeText(result);
+      const copied = await copyToClipboard(
+        result,
+        () => this.gateway.isCurrent(scope) && attempt === this.copyResultAttempt,
+      );
+      if (this.gateway.isCurrent(scope) && attempt === this.copyResultAttempt) {
+        this.copyResultError = copied ? null : t("common.copyFailed");
+      }
     } catch (error) {
-      if (this.gateway.isCurrent(scope)) {
-        this.error = formatUiError(error, t("tasksPage.recoveryFailed"));
+      if (this.gateway.isCurrent(scope) && attempt === this.copyResultAttempt) {
+        this.copyResultError = formatUiError(error, t("tasksPage.recoveryFailed"));
       }
     }
   }
@@ -413,6 +429,7 @@ class TasksPage extends OpenClawLightDomElement {
         canCancel: hasOperatorWriteAccess(this.context.gateway.snapshot.hello?.auth ?? null),
         loading: this.listTask.status === TaskStatus.PENDING,
         error: this.error,
+        copyResultError: this.copyResultError,
         tasks: this.tasks,
         cancellingTaskIds: this.cancellingTaskIds,
         sessionRow: (sessionKey) => findUiSessionRow(this.context, sessionKey),
diff --git a/ui/src/pages/tasks/tasks.e2e.test.ts b/ui/src/pages/tasks/tasks.e2e.test.ts
index 2bf2917aac19..169e9467773f 100644
--- a/ui/src/pages/tasks/tasks.e2e.test.ts
+++ b/ui/src/pages/tasks/tasks.e2e.test.ts
@@ -81,6 +81,19 @@ const readOnlyRetainedTask = {
 };
 
 const readOnlyRetainedResult = "Synthetic retained result copied by a read-only operator.";
+const olderRetainedResult = "Older retained result from the first copy activation.";
+const newestRetainedResult = "Newest retained result from the second copy activation.";
+
+type ClipboardFaultState = {
+  asyncWrites: string[];
+  execSucceeds: boolean;
+  legacyWrites: string[];
+  mode: "defer" | "missing" | "reject";
+  pending: Array<{
+    reject: (reason?: unknown) => void;
+    resolve: () => void;
+  }>;
+};
 
 const retryBlockedTask = {
   ...readOnlyRetainedTask,
@@ -484,15 +497,50 @@ suite.define(() => {
     }
   });
 
-  it("lets an operator.read-only user copy a retained result without mutations", async () => {
+  it("copies retained results through fallback and announces total failure", async () => {
     await mkdir(artifactDir, { recursive: true });
     const context = await suite.browser.newContext({
       locale: "en-US",
       serviceWorkers: "block",
       viewport: { width: 1440, height: 900 },
     });
-    await context.grantPermissions(["clipboard-read", "clipboard-write"], {
-      origin: new URL(suite.server.baseUrl).origin,
+    await context.addInitScript(() => {
+      const state: ClipboardFaultState = {
+        asyncWrites: [],
+        execSucceeds: true,
+        legacyWrites: [],
+        mode: "reject",
+        pending: [],
+      };
+      Object.defineProperty(window, "tasksClipboardFault", { value: state });
+      Object.defineProperty(navigator, "clipboard", {
+        configurable: true,
+        get: () =>
+          state.mode === "missing"
+            ? undefined
+            : {
+                writeText(text: string) {
+                  state.asyncWrites.push(text);
+                  if (state.mode === "defer") {
+                    return new Promise<void>((resolve, reject) => {
+                      state.pending.push({ reject, resolve });
+                    });
+                  }
+                  return Promise.reject(
+                    new DOMException("Clipboard access denied", "NotAllowedError"),
+                  );
+                },
+              },
+      });
+      document.execCommand = (command: string) => {
+        if (command !== "copy") {
+          return false;
+        }
+        state.legacyWrites.push(
+          document.querySelector<HTMLTextAreaElement>("textarea")?.value ?? "",
+        );
+        return state.execSucceeds;
+      };
     });
     const page = await context.newPage();
     try {
@@ -512,7 +560,13 @@ suite.define(() => {
             ],
           },
           "tasks.get": {
-            task: { ...readOnlyRetainedTask, result: readOnlyRetainedResult },
+            sequence: [
+              { task: { ...readOnlyRetainedTask, result: readOnlyRetainedResult } },
+              { task: { ...readOnlyRetainedTask, result: readOnlyRetainedResult } },
+              { task: { ...readOnlyRetainedTask, result: readOnlyRetainedResult } },
+              { task: { ...readOnlyRetainedTask, result: olderRetainedResult } },
+              { task: { ...readOnlyRetainedTask, result: newestRetainedResult } },
+            ],
           },
         },
       });
@@ -533,11 +587,166 @@ suite.define(() => {
       const copyButton = task.getByRole("button", { name: "Copy result" });
       await copyButton.waitFor({ state: "visible" });
       await copyButton.click();
-      const getRequest = await gateway.waitForRequest("tasks.get");
-      expect(getRequest.params).toEqual({ taskId: readOnlyRetainedTask.taskId });
       await expect
-        .poll(() => page.evaluate(() => navigator.clipboard.readText()))
-        .toBe(readOnlyRetainedResult);
+        .poll(() =>
+          page.evaluate(
+            () =>
+              (window as typeof window & { tasksClipboardFault: ClipboardFaultState })
+                .tasksClipboardFault,
+          ),
+        )
+        .toMatchObject({
+          asyncWrites: [readOnlyRetainedResult],
+          legacyWrites: [readOnlyRetainedResult],
+        });
+
+      await page.evaluate(() => {
+        (
+          window as typeof window & { tasksClipboardFault: ClipboardFaultState }
+        ).tasksClipboardFault.mode = "missing";
+      });
+      await copyButton.click();
+      await expect
+        .poll(() =>
+          page.evaluate(
+            () =>
+              (window as typeof window & { tasksClipboardFault: ClipboardFaultState })
+                .tasksClipboardFault,
+          ),
+        )
+        .toMatchObject({
+          asyncWrites: [readOnlyRetainedResult],
+          legacyWrites: [readOnlyRetainedResult, readOnlyRetainedResult],
+        });
+
+      await page.evaluate(() => {
+        const state = (window as typeof window & { tasksClipboardFault: ClipboardFaultState })
+          .tasksClipboardFault;
+        state.mode = "reject";
+        state.execSucceeds = false;
+      });
+      await copyButton.click();
+      await expect.poll(() => page.getByRole("alert").textContent()).toBe("Copy failed");
+      await page.screenshot({ path: path.join(artifactDir, "05-copy-failed.png") });
+      expect(
+        await page.evaluate(
+          () =>
+            (window as typeof window & { tasksClipboardFault: ClipboardFaultState })
+              .tasksClipboardFault,
+        ),
+      ).toMatchObject({
+        asyncWrites: [readOnlyRetainedResult, readOnlyRetainedResult],
+        legacyWrites: [readOnlyRetainedResult, readOnlyRetainedResult, readOnlyRetainedResult],
+      });
+
+      await page.evaluate(() => {
+        const state = (window as typeof window & { tasksClipboardFault: ClipboardFaultState })
+          .tasksClipboardFault;
+        state.mode = "defer";
+        state.execSucceeds = false;
+      });
+      await copyButton.click();
+      await copyButton.click();
+      await expect
+        .poll(() =>
+          page.evaluate(
+            () =>
+              (window as typeof window & { tasksClipboardFault: ClipboardFaultState })
+                .tasksClipboardFault.pending.length,
+          ),
+        )
+        .toBe(2);
+      await page.evaluate(() => {
+        (
+          window as typeof window & { tasksClipboardFault: ClipboardFaultState }
+        ).tasksClipboardFault.pending[1]?.reject(
+          new DOMException("Clipboard access denied", "NotAllowedError"),
+        );
+      });
+      await expect
+        .poll(() =>
+          page.evaluate(
+            () =>
+              (window as typeof window & { tasksClipboardFault: ClipboardFaultState })
+                .tasksClipboardFault.legacyWrites.length,
+          ),
+        )
+        .toBe(4);
+      await page.evaluate(() => {
+        (
+          window as typeof window & { tasksClipboardFault: ClipboardFaultState }
+        ).tasksClipboardFault.pending[0]?.reject(
+          new DOMException("Clipboard access denied", "NotAllowedError"),
+        );
+      });
+      await page.evaluate(
+        () =>
+          new Promise<void>((resolve) => {
+            window.setTimeout(resolve, 0);
+          }),
+      );
+      const currentAlert = page.getByRole("alert");
+      expect(await currentAlert.count()).toBe(1);
+      expect(await currentAlert.textContent()).toBe("Copy failed");
+      expect(
+        await page.evaluate(
+          () =>
+            (window as typeof window & { tasksClipboardFault: ClipboardFaultState })
+              .tasksClipboardFault.legacyWrites,
+        ),
+      ).toEqual([
+        readOnlyRetainedResult,
+        readOnlyRetainedResult,
+        readOnlyRetainedResult,
+        newestRetainedResult,
+      ]);
+
+      await gateway.deferNext("tasks.get", { taskId: readOnlyRetainedTask.taskId });
+      await copyButton.click();
+      await expect.poll(() => gateway.getRequests("tasks.get")).toHaveLength(6);
+      expect(await page.getByRole("alert").textContent()).toBe("Copy failed");
+      const socketCount = await gateway.getSocketCount();
+      await gateway.closeLatest(1012, "retire retained-result copy");
+      await expect.poll(() => gateway.getSocketCount()).toBeGreaterThan(socketCount);
+      await gateway.resolveDeferred("tasks.get", {
+        task: { ...readOnlyRetainedTask, result: readOnlyRetainedResult },
+      });
+      await page.evaluate(
+        () =>
+          new Promise<void>((resolve) => {
+            window.setTimeout(resolve, 0);
+          }),
+      );
+      expect(await page.getByRole("alert").count()).toBe(0);
+      expect(
+        await page.evaluate(
+          () =>
+            (window as typeof window & { tasksClipboardFault: ClipboardFaultState })
+              .tasksClipboardFault,
+        ),
+      ).toMatchObject({
+        asyncWrites: [
+          readOnlyRetainedResult,
+          readOnlyRetainedResult,
+          olderRetainedResult,
+          newestRetainedResult,
+        ],
+        legacyWrites: [
+          readOnlyRetainedResult,
+          readOnlyRetainedResult,
+          readOnlyRetainedResult,
+          newestRetainedResult,
+        ],
+      });
+
+      expect((await gateway.getRequests("tasks.get")).map((request) => request.params)).toEqual([
+        { taskId: readOnlyRetainedTask.taskId },
+        { taskId: readOnlyRetainedTask.taskId },
+        { taskId: readOnlyRetainedTask.taskId },
+        { taskId: readOnlyRetainedTask.taskId },
+        { taskId: readOnlyRetainedTask.taskId },
+        { taskId: readOnlyRetainedTask.taskId },
+      ]);
       expect(await gateway.getRequests("tasks.retry")).toHaveLength(0);
       expect(await gateway.getRequests("tasks.dismiss")).toHaveLength(0);
       expect(await gateway.getRequests("tasks.cancel")).toHaveLength(0);
diff --git a/ui/src/pages/tasks/view.ts b/ui/src/pages/tasks/view.ts
index 2e5c01e91c3c..d649ae9d1ddb 100644
--- a/ui/src/pages/tasks/view.ts
+++ b/ui/src/pages/tasks/view.ts
@@ -29,6 +29,7 @@ type TasksProps = {
   canCancel: boolean;
   loading: boolean;
   error: string | null;
+  copyResultError: string | null;
   tasks: TaskSummary[];
   cancellingTaskIds: ReadonlySet<string>;
   sessionRow: (sessionKey: string) => GatewaySessionRow | undefined;
@@ -255,7 +256,10 @@ export function renderTasks(props: TasksProps) {
       ${!props.connected
         ? html`<div class="callout warn">${t("tasksPage.disconnected")}</div>`
         : nothing}
-      ${props.error ? html`<div class="callout danger">${props.error}</div>` : nothing}
+      ${props.error ? html`<div class="callout danger" role="alert">${props.error}</div>` : nothing}
+      ${props.copyResultError
+        ? html`<div class="callout danger" role="alert">${props.copyResultError}</div>`
+        : nothing}
       ${renderSummaryStrip(props.tasks)}
       ${props.loading && props.tasks.length === 0
         ? html`<div class="card muted">${t("tasksPage.loading")}</div>`

From 7d83ff7c8fffa7ffc232a16e3b4034443e174bf9 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 07:37:16 -0700
Subject: [PATCH 007/124] improve(terminal): speed up fitting table rendering
 (#127221)

* test(terminal): cover fitting table cell rendering

Amp-Thread-ID: https://ampcode.com/threads/T-01a0242a-0302-708f-a777-ec7c0a5c9c60

* perf(terminal): skip wrapping work for fitting ASCII cells

Amp-Thread-ID: https://ampcode.com/threads/T-01a021f5-984a-7628-a30c-491c166ff247

---------

Co-authored-by: Amp <amp@ampcode.com>
---
 packages/terminal-core/src/table.test.ts | 15 +++++++++++++++
 packages/terminal-core/src/table.ts      | 10 ++++++++--
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/packages/terminal-core/src/table.test.ts b/packages/terminal-core/src/table.test.ts
index 2f44ecc55318..488208b72240 100644
--- a/packages/terminal-core/src/table.test.ts
+++ b/packages/terminal-core/src/table.test.ts
@@ -70,6 +70,21 @@ describe("renderTable", () => {
     vi.restoreAllMocks();
   });
 
+  it("renders fitting ASCII cells without grapheme segmentation", () => {
+    const segment = vi.spyOn(Intl.Segmenter.prototype, "segment");
+
+    const out = renderTable({
+      border: "ascii",
+      columns: [{ key: "Name", header: "Name" }],
+      rows: [{ Name: "alpha" }, { Name: "beta" }],
+    });
+
+    expect(out).toBe(
+      ["+-------+", "| Name  |", "+-------+", "| alpha |", "| beta  |", "+-------+", ""].join("\n"),
+    );
+    expect(segment).not.toHaveBeenCalled();
+  });
+
   it.each(["$&", "$`", "$'", "$$"])(
     "displays a literal %s home path in terminal tables",
     (pattern) => {
diff --git a/packages/terminal-core/src/table.ts b/packages/terminal-core/src/table.ts
index 7ac971acccb7..1f0bd1112365 100644
--- a/packages/terminal-core/src/table.ts
+++ b/packages/terminal-core/src/table.ts
@@ -55,8 +55,9 @@ function padCell(text: string, width: number, align: Align): string {
   // A single grapheme wider than the cell (e.g. a width-2 CJK/emoji glyph in a
   // width-1 column) survives wrapLine intact, so clamp here to keep every cell
   // exactly `width` columns and preserve the border-alignment invariant.
-  const content = visibleWidth(text) > width ? truncateToVisibleWidth(text, width) : text;
-  const w = visibleWidth(content);
+  const textWidth = visibleWidth(text);
+  const content = textWidth > width ? truncateToVisibleWidth(text, width) : text;
+  const w = content === text ? textWidth : visibleWidth(content);
   if (w >= width) {
     return content;
   }
@@ -366,6 +367,11 @@ function wrapLine(text: string, width: number): string[] {
   if (width <= 0) {
     return [text];
   }
+  // Fitting edge-trimmed ASCII is one column per code unit and needs no ANSI/grapheme scan.
+  // Keep edge whitespace on the full path, where wrapping preserves its trimming semantics.
+  if (text.length <= width && /^[!-~](?:[ -~]*[!-~])?$/u.test(text)) {
+    return [text];
+  }
 
   // ANSI-aware wrapping: never split inside ANSI SGR/OSC-8 sequences.
   // Table cells are padded and bordered per physical line, so wrapped lines

From 03d4b8a9c3313138886c901addf9231b96c67371 Mon Sep 17 00:00:00 2001
From: "Vyctor H. Brzezowski" <krzyszchweski@gmail.com>
Date: Fri, 21 Aug 2026 11:37:36 -0300
Subject: [PATCH 008/124] fix(ui): expose active split pane to assistive tech
 (#127213)

---
 ui/src/pages/chat/chat-page-pane-render.ts |  3 ++-
 ui/src/pages/chat/chat-page.test.ts        | 11 +++++++++++
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/ui/src/pages/chat/chat-page-pane-render.ts b/ui/src/pages/chat/chat-page-pane-render.ts
index 479c5dfedba6..5316db743c36 100644
--- a/ui/src/pages/chat/chat-page-pane-render.ts
+++ b/ui/src/pages/chat/chat-page-pane-render.ts
@@ -1,4 +1,4 @@
-import { html } from "lit";
+import { html, nothing } from "lit";
 import { repeat } from "lit/directives/repeat.js";
 import type { ApplicationContext } from "../../app/context.ts";
 import { nativeGatewaysCapability } from "../../app/native-gateways.runtime.ts";
@@ -55,6 +55,7 @@ export function renderChatPagePaneCell(options: ChatPagePaneRenderOptions) {
       class="chat-split-view__cell ${options.splitMode && options.active
         ? "chat-split-view__cell--active"
         : ""} ${options.narrow && !options.active ? "chat-split-view__cell--narrow-hidden" : ""}"
+      aria-current=${options.splitMode && options.active ? "true" : nothing}
       style="flex: ${options.weight} 1 0"
       @pointerdown=${() => options.onFocusPane(options.pane.id)}
       @focusin=${() => options.onFocusPane(options.pane.id)}
diff --git a/ui/src/pages/chat/chat-page.test.ts b/ui/src/pages/chat/chat-page.test.ts
index 639f887304e8..bd700437099d 100644
--- a/ui/src/pages/chat/chat-page.test.ts
+++ b/ui/src/pages/chat/chat-page.test.ts
@@ -654,9 +654,11 @@ describe("chat page split layout host", () => {
     await page.updateComplete;
 
     const panes = [...page.querySelectorAll<RenderedPane>("openclaw-chat-pane")];
+    const cells = [...page.querySelectorAll<HTMLElement>(".chat-split-view__cell")];
     const dividers = page.querySelectorAll<RenderedDivider>("resizable-divider");
     expect(panes.map((pane) => pane.paneId)).toEqual(["p1", "p2"]);
     expect(panes.map((pane) => pane.active)).toEqual([false, true]);
+    expect(cells.map((cell) => cell.getAttribute("aria-current"))).toEqual([null, "true"]);
     expect(dividers).toHaveLength(1);
     expect(itemAt(dividers, 0, "split divider").orientation).toBe("vertical");
     expect(
@@ -666,6 +668,15 @@ describe("chat page split layout host", () => {
     ).toBe(true);
     expect(panes.every((pane) => pane.onOpenSplitView === undefined)).toBe(true);
     expect(panes[0]?.chatMessagesBySession).toBe(panes[1]?.chatMessagesBySession);
+
+    itemAt(cells, 0, "split cell").dispatchEvent(new Event("pointerdown"));
+    await page.updateComplete;
+
+    expect(
+      [...page.querySelectorAll<HTMLElement>(".chat-split-view__cell")].map((cell) =>
+        cell.getAttribute("aria-current"),
+      ),
+    ).toEqual(["true", null]);
   });
 
   it("declares split panes, session switches, pane closes, and page disposal", async () => {

From 7833e242cb25a5be7ee6485aafe975bc7e4eb6dd Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Fri, 21 Aug 2026 07:54:56 -0700
Subject: [PATCH 009/124] fix(ci): isolate performance candidate trust
 (#127160)

---
 .github/workflows/openclaw-performance.yml    |  89 ++++++--
 .../openclaw-performance-workflow.test.ts     | 212 +++++++++++++++++-
 2 files changed, 279 insertions(+), 22 deletions(-)

diff --git a/.github/workflows/openclaw-performance.yml b/.github/workflows/openclaw-performance.yml
index e3b85def4865..81aa0897a810 100644
--- a/.github/workflows/openclaw-performance.yml
+++ b/.github/workflows/openclaw-performance.yml
@@ -93,6 +93,8 @@ jobs:
       kova_ref: ${{ steps.resolve.outputs.kova_ref }}
       kova_config_contract: ${{ steps.resolve.outputs.kova_config_contract }}
       kova_ref_trusted_for_live: ${{ steps.resolve.outputs.kova_ref_trusted_for_live }}
+      secret_eligible: ${{ steps.candidate_trust.outputs.secret_eligible }}
+      cache_write_allowed: ${{ steps.candidate_trust.outputs.cache_write_allowed }}
     steps:
       - name: Checkout target metadata
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
@@ -177,6 +179,34 @@ jobs:
             echo "kova_ref_trusted_for_live=false" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Classify performance candidate trust
+        id: candidate_trust
+        env:
+          CANDIDATE_SHA: ${{ steps.resolve.outputs.tested_sha }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+          WORKFLOW_SHA: ${{ github.workflow_sha }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          secret_eligible=false
+          cache_write_allowed=false
+          if [[
+            "$GITHUB_EVENT_NAME" == "schedule" ||
+            "$GITHUB_EVENT_NAME" == "workflow_dispatch"
+          ]] && [[
+            "$GITHUB_REF" == "refs/heads/${DEFAULT_BRANCH}" &&
+            "$CANDIDATE_SHA" == "$WORKFLOW_SHA"
+          ]]; then
+            secret_eligible=true
+            cache_write_allowed=true
+          fi
+
+          {
+            echo "secret_eligible=$secret_eligible"
+            echo "cache_write_allowed=$cache_write_allowed"
+          } >> "$GITHUB_OUTPUT"
+
   kova:
     name: ${{ matrix.title }}
     needs: resolve_target
@@ -234,6 +264,7 @@ jobs:
       MATRIX_DEEP_PROFILE: ${{ matrix.deep_profile }}
       MATRIX_LIVE: ${{ matrix.live }}
       KOVA_REF_TRUSTED_FOR_LIVE: ${{ needs.resolve_target.outputs.kova_ref_trusted_for_live }}
+      SECRET_ELIGIBLE: ${{ needs.resolve_target.outputs.secret_eligible }}
     steps:
       - name: Decide lane
         id: lane
@@ -250,6 +281,10 @@ jobs:
             run_lane=false
             reason="live_openai_candidate input is false"
           fi
+          if [[ "$LANE_ID" == "live-openai-candidate" && "$run_lane" == "true" && "$SECRET_ELIGIBLE" != "true" ]]; then
+            run_lane=false
+            reason="candidate is not eligible for live credentials"
+          fi
           if [[ "$LANE_ID" == "live-openai-candidate" && "$run_lane" == "true" && "$KOVA_REF_TRUSTED_FOR_LIVE" != "true" ]]; then
             echo "::error::The live OpenAI lane only executes a reviewed immutable Kova default. Omit kova_ref or update the pinned workflow defaults after review."
             exit 1
@@ -271,7 +306,7 @@ jobs:
         if: steps.lane.outputs.run == 'true'
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
-          ref: ${{ github.sha }}
+          ref: ${{ github.workflow_sha }}
           path: .artifacts/performance-workflow
           fetch-depth: 1
           persist-credentials: false
@@ -295,11 +330,35 @@ jobs:
             echo "Workflow SHA: ${GITHUB_SHA}"
           } >> "$GITHUB_STEP_SUMMARY"
 
+      - name: Stage trusted setup action graph
+        if: steps.lane.outputs.run == 'true'
+        shell: bash
+        run: &stage_trusted_performance_setup |
+          set -euo pipefail
+          github_dir="$GITHUB_WORKSPACE/.github"
+          actions_dir="$github_dir/actions"
+          trusted_action="$PERFORMANCE_HELPER_DIR/.github/actions/setup-pnpm-store-cache"
+
+          test -f "$trusted_action/action.yml"
+          test -f "$trusted_action/ensure-node.sh"
+          if [[ -L "$github_dir" || ( -e "$github_dir" && ! -d "$github_dir" ) ]]; then
+            rm -rf -- "$github_dir"
+          fi
+          mkdir -p "$github_dir"
+          if [[ -L "$actions_dir" || ( -e "$actions_dir" && ! -d "$actions_dir" ) ]]; then
+            rm -rf -- "$actions_dir"
+          fi
+          mkdir -p "$actions_dir"
+          rm -rf -- "$actions_dir/setup-pnpm-store-cache"
+          cp -R -- "$trusted_action" "$actions_dir/setup-pnpm-store-cache"
+          cmp "$trusted_action/action.yml" "$actions_dir/setup-pnpm-store-cache/action.yml"
+          cmp "$trusted_action/ensure-node.sh" "$actions_dir/setup-pnpm-store-cache/ensure-node.sh"
+
       - name: Set up Node environment
         if: steps.lane.outputs.run == 'true'
-        uses: ./.github/actions/setup-node-env
+        uses: ./.artifacts/performance-workflow/.github/actions/setup-node-env
         with:
-          cache-mode: restore
+          cache-mode: ${{ needs.resolve_target.outputs.cache_write_allowed == 'true' && 'restore' || 'off' }}
           install-bun: "false"
 
       - name: Prepare systemd user session
@@ -448,7 +507,7 @@ jobs:
           echo "KOVA_LANE_REPEAT=$repeat" >> "$GITHUB_ENV"
 
       - name: Configure live OpenAI auth
-        if: ${{ steps.lane.outputs.run == 'true' && matrix.live == 'true' }}
+        if: ${{ steps.lane.outputs.run == 'true' && matrix.live == 'true' && needs.resolve_target.outputs.secret_eligible == 'true' }}
         env:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL }}
@@ -466,8 +525,8 @@ jobs:
         id: kova
         if: steps.lane.outputs.run == 'true'
         env:
-          OPENAI_API_KEY: ${{ matrix.live == 'true' && secrets.OPENAI_API_KEY || '' }}
-          OPENAI_BASE_URL: ${{ matrix.live == 'true' && secrets.OPENAI_BASE_URL || '' }}
+          OPENAI_API_KEY: ${{ matrix.live == 'true' && needs.resolve_target.outputs.secret_eligible == 'true' && secrets.OPENAI_API_KEY || '' }}
+          OPENAI_BASE_URL: ${{ matrix.live == 'true' && needs.resolve_target.outputs.secret_eligible == 'true' && secrets.OPENAI_BASE_URL || '' }}
         shell: bash
         run: |
           set -euo pipefail
@@ -646,7 +705,7 @@ jobs:
       - name: Checkout source performance helpers
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
-          ref: ${{ github.sha }}
+          ref: ${{ github.workflow_sha }}
           path: .artifacts/performance-workflow
           fetch-depth: 1
           persist-credentials: false
@@ -667,10 +726,14 @@ jobs:
             echo "Workflow SHA: ${GITHUB_SHA}"
           } >> "$GITHUB_STEP_SUMMARY"
 
+      - name: Stage trusted source setup action graph
+        shell: bash
+        run: *stage_trusted_performance_setup
+
       - name: Set up source performance environment
-        uses: ./.github/actions/setup-node-env
+        uses: ./.artifacts/performance-workflow/.github/actions/setup-node-env
         with:
-          cache-mode: restore
+          cache-mode: ${{ needs.resolve_target.outputs.cache_write_allowed == 'true' && 'restore' || 'off' }}
           install-bun: "false"
 
       - name: Fetch previous source performance baseline
@@ -925,7 +988,7 @@ jobs:
   publish:
     name: Publish ${{ matrix.title }} report
     needs: [resolve_target, kova, source_performance]
-    if: ${{ always() && (github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.publish_reports == true)) && needs.resolve_target.result == 'success' && needs.kova.result != 'cancelled' && needs.source_performance.result != 'cancelled' }}
+    if: ${{ always() && needs.resolve_target.outputs.secret_eligible == 'true' && (github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.publish_reports == true)) && needs.resolve_target.result == 'success' && needs.kova.result != 'cancelled' && needs.source_performance.result != 'cancelled' }}
     runs-on: ubuntu-24.04
     timeout-minutes: 30
     permissions:
@@ -966,7 +1029,7 @@ jobs:
         if: steps.lane.outputs.run == 'true'
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
-          ref: ${{ github.sha }}
+          ref: ${{ github.workflow_sha }}
           path: .artifacts/performance-publisher
           sparse-checkout: |
             scripts/lib/kova-report-publish-files.mjs
@@ -1246,7 +1309,7 @@ jobs:
 
       - name: Create clawgrit reports app token
         id: clawgrit_app_token
-        if: ${{ steps.prepare.outputs.ready == 'true' && steps.prepare.outputs.already_published != 'true' }}
+        if: ${{ needs.resolve_target.outputs.secret_eligible == 'true' && steps.prepare.outputs.ready == 'true' && steps.prepare.outputs.already_published != 'true' }}
         continue-on-error: ${{ env.REPORT_PUBLISH_REQUIRED != 'true' }}
         uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
         with:
@@ -1257,7 +1320,7 @@ jobs:
           permission-contents: write
 
       - name: Publish to clawgrit reports
-        if: ${{ steps.prepare.outputs.ready == 'true' && steps.prepare.outputs.already_published != 'true' }}
+        if: ${{ needs.resolve_target.outputs.secret_eligible == 'true' && steps.prepare.outputs.ready == 'true' && steps.prepare.outputs.already_published != 'true' }}
         continue-on-error: ${{ env.REPORT_PUBLISH_REQUIRED != 'true' }}
         env:
           CLAWGRIT_REPORTS_APP_TOKEN: ${{ steps.clawgrit_app_token.outputs.token }}
diff --git a/test/scripts/openclaw-performance-workflow.test.ts b/test/scripts/openclaw-performance-workflow.test.ts
index cad75f99ea91..dc66077c4475 100644
--- a/test/scripts/openclaw-performance-workflow.test.ts
+++ b/test/scripts/openclaw-performance-workflow.test.ts
@@ -74,6 +74,46 @@ function kovaMatrixEntries(): Array<Record<string, string>> {
   return readWorkflow().jobs?.kova?.strategy?.matrix?.include ?? [];
 }
 
+function runCandidateTrustClassification({
+  candidateSha,
+  eventName,
+  ref,
+  workflowSha,
+}: {
+  candidateSha: string;
+  eventName: "schedule" | "workflow_dispatch";
+  ref: string;
+  workflowSha: string;
+}) {
+  const step = findStep("Classify performance candidate trust", "resolve_target");
+  const root = tempDirs.make("openclaw-performance-candidate-trust-");
+  const output = join(root, "output");
+  const result = spawnSync("bash", ["-c", step.run ?? ""], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      CANDIDATE_SHA: candidateSha,
+      DEFAULT_BRANCH: "main",
+      GITHUB_EVENT_NAME: eventName,
+      GITHUB_OUTPUT: output,
+      GITHUB_REF: ref,
+      WORKFLOW_SHA: workflowSha,
+    },
+  });
+  const outputs = Object.fromEntries(
+    existsSync(output)
+      ? readFileSync(output, "utf8")
+          .trim()
+          .split("\n")
+          .map((line) => {
+            const separator = line.indexOf("=");
+            return [line.slice(0, separator), line.slice(separator + 1)];
+          })
+      : [],
+  );
+  return { outputs, result };
+}
+
 describe("OpenClaw performance workflow", () => {
   it("uses an optional dispatch identifier to name parent-owned runs", () => {
     const workflow = readFileSync(WORKFLOW, "utf8");
@@ -195,13 +235,13 @@ describe("OpenClaw performance workflow", () => {
       decideLane.run?.indexOf('echo "run=$run_lane"') ?? -1,
     );
     expect(configureLiveAuth.if).toBe(
-      "${{ steps.lane.outputs.run == 'true' && matrix.live == 'true' }}",
+      "${{ steps.lane.outputs.run == 'true' && matrix.live == 'true' && needs.resolve_target.outputs.secret_eligible == 'true' }}",
     );
     expect(runKova.env?.OPENAI_API_KEY).toBe(
-      "${{ matrix.live == 'true' && secrets.OPENAI_API_KEY || '' }}",
+      "${{ matrix.live == 'true' && needs.resolve_target.outputs.secret_eligible == 'true' && secrets.OPENAI_API_KEY || '' }}",
     );
     expect(runKova.env?.OPENAI_BASE_URL).toBe(
-      "${{ matrix.live == 'true' && secrets.OPENAI_BASE_URL || '' }}",
+      "${{ matrix.live == 'true' && needs.resolve_target.outputs.secret_eligible == 'true' && secrets.OPENAI_BASE_URL || '' }}",
     );
 
     try {
@@ -212,6 +252,7 @@ describe("OpenClaw performance workflow", () => {
           GITHUB_OUTPUT: output,
           KOVA_REF_TRUSTED_FOR_LIVE: "false",
           LANE_ID: "live-openai-candidate",
+          SECRET_ELIGIBLE: "true",
         },
       });
       expect(rejected.status).toBe(1);
@@ -226,6 +267,7 @@ describe("OpenClaw performance workflow", () => {
           GITHUB_OUTPUT: output,
           KOVA_REF_TRUSTED_FOR_LIVE: "true",
           LANE_ID: "live-openai-candidate",
+          SECRET_ELIGIBLE: "true",
         },
       });
       expect(accepted.status).toBe(0);
@@ -235,6 +277,157 @@ describe("OpenClaw performance workflow", () => {
     }
   });
 
+  it("keeps arbitrary performance candidates secretless and cacheless", () => {
+    const workflow = readWorkflow();
+    const trust = findStep("Classify performance candidate trust", "resolve_target");
+    const decideLane = findStep("Decide lane");
+    const kovaHarness = findStep("Checkout performance workflow helpers");
+    const kovaStage = findStep("Stage trusted setup action graph");
+    const kovaSetup = findStep("Set up Node environment");
+    const sourceHarness = findStep("Checkout source performance helpers", "source_performance");
+    const sourceStage = findStep("Stage trusted source setup action graph", "source_performance");
+    const sourceSetup = findStep("Set up source performance environment", "source_performance");
+    const publisherHarness = findStep("Checkout performance publisher helper", "publish");
+
+    expect(workflow.jobs?.resolve_target?.outputs).toMatchObject({
+      secret_eligible: "${{ steps.candidate_trust.outputs.secret_eligible }}",
+      cache_write_allowed: "${{ steps.candidate_trust.outputs.cache_write_allowed }}",
+    });
+    expect(trust.env).toMatchObject({
+      CANDIDATE_SHA: "${{ steps.resolve.outputs.tested_sha }}",
+      DEFAULT_BRANCH: "${{ github.event.repository.default_branch }}",
+      WORKFLOW_SHA: "${{ github.workflow_sha }}",
+    });
+    expect(trust.run).toContain("secret_eligible=false");
+    expect(trust.run).toContain("cache_write_allowed=false");
+    expect(trust.run).toContain('"$GITHUB_REF" == "refs/heads/${DEFAULT_BRANCH}"');
+    expect(trust.run).toContain('"$CANDIDATE_SHA" == "$WORKFLOW_SHA"');
+    expect(trust.run).toContain("secret_eligible=true");
+    expect(trust.run).toContain("cache_write_allowed=true");
+
+    for (const harness of [kovaHarness, sourceHarness, publisherHarness]) {
+      expect(harness.with?.ref).toBe("${{ github.workflow_sha }}");
+      expect(harness.with?.["persist-credentials"]).toBe(false);
+    }
+    for (const setup of [kovaSetup, sourceSetup]) {
+      expect(setup.uses).toBe("./.artifacts/performance-workflow/.github/actions/setup-node-env");
+      expect(setup.with?.["cache-mode"]).toBe(
+        "${{ needs.resolve_target.outputs.cache_write_allowed == 'true' && 'restore' || 'off' }}",
+      );
+    }
+    expect(kovaStage.run).toBe(sourceStage.run);
+    for (const stage of [kovaStage, sourceStage]) {
+      expect(stage.run).toContain(
+        'trusted_action="$PERFORMANCE_HELPER_DIR/.github/actions/setup-pnpm-store-cache"',
+      );
+      expect(stage.run).toContain('rm -rf -- "$actions_dir/setup-pnpm-store-cache"');
+      expect(stage.run).toContain(
+        'cp -R -- "$trusted_action" "$actions_dir/setup-pnpm-store-cache"',
+      );
+      expect(stage.run).toContain(
+        'cmp "$trusted_action/action.yml" "$actions_dir/setup-pnpm-store-cache/action.yml"',
+      );
+      expect(stage.run).toContain(
+        'cmp "$trusted_action/ensure-node.sh" "$actions_dir/setup-pnpm-store-cache/ensure-node.sh"',
+      );
+    }
+    const kovaSteps = workflow.jobs?.kova?.steps ?? [];
+    const sourceSteps = workflow.jobs?.source_performance?.steps ?? [];
+    expect(kovaSteps.findIndex((step) => step.name === kovaStage.name)).toBeLessThan(
+      kovaSteps.findIndex((step) => step.name === kovaSetup.name),
+    );
+    expect(sourceSteps.findIndex((step) => step.name === sourceStage.name)).toBeLessThan(
+      sourceSteps.findIndex((step) => step.name === sourceSetup.name),
+    );
+    expect(decideLane.run).toContain(
+      'if [[ "$LANE_ID" == "live-openai-candidate" && "$run_lane" == "true" && "$SECRET_ELIGIBLE" != "true" ]]; then',
+    );
+    expect(decideLane.run).toContain('reason="candidate is not eligible for live credentials"');
+
+    const trustedSha = "a".repeat(40);
+    for (const eventName of ["schedule", "workflow_dispatch"] as const) {
+      const trusted = runCandidateTrustClassification({
+        candidateSha: trustedSha,
+        eventName,
+        ref: "refs/heads/main",
+        workflowSha: trustedSha,
+      });
+      expect(trusted.result.status, trusted.result.stderr).toBe(0);
+      expect(trusted.outputs).toEqual({
+        secret_eligible: "true",
+        cache_write_allowed: "true",
+      });
+    }
+
+    for (const candidate of [
+      {
+        candidateSha: "b".repeat(40),
+        eventName: "workflow_dispatch" as const,
+        ref: "refs/heads/main",
+        workflowSha: trustedSha,
+      },
+      {
+        candidateSha: trustedSha,
+        eventName: "workflow_dispatch" as const,
+        ref: "refs/heads/release/2026.8.1",
+        workflowSha: trustedSha,
+      },
+    ]) {
+      const untrusted = runCandidateTrustClassification(candidate);
+      expect(untrusted.result.status, untrusted.result.stderr).toBe(0);
+      expect(untrusted.outputs).toEqual({
+        secret_eligible: "false",
+        cache_write_allowed: "false",
+      });
+    }
+  });
+
+  it("replaces candidate-owned nested setup actions with the trusted workflow copy", () => {
+    const stages = [
+      findStep("Stage trusted setup action graph"),
+      findStep("Stage trusted source setup action graph", "source_performance"),
+    ];
+
+    for (const stage of stages) {
+      const root = tempDirs.make("openclaw-performance-action-graph-");
+      const workspace = join(root, "candidate");
+      const helper = join(root, "workflow");
+      const candidateAction = join(workspace, ".github/actions/setup-pnpm-store-cache/action.yml");
+      const candidateEnsureNode = join(
+        workspace,
+        ".github/actions/setup-pnpm-store-cache/ensure-node.sh",
+      );
+      const trustedAction = join(helper, ".github/actions/setup-pnpm-store-cache/action.yml");
+      const trustedEnsureNode = join(
+        helper,
+        ".github/actions/setup-pnpm-store-cache/ensure-node.sh",
+      );
+      mkdirSync(join(workspace, ".github/actions/setup-pnpm-store-cache"), {
+        recursive: true,
+      });
+      mkdirSync(join(helper, ".github/actions/setup-pnpm-store-cache"), {
+        recursive: true,
+      });
+      writeFileSync(candidateAction, "candidate action\n");
+      writeFileSync(candidateEnsureNode, "candidate script\n");
+      writeFileSync(trustedAction, "trusted action\n");
+      writeFileSync(trustedEnsureNode, "trusted script\n");
+
+      const result = spawnSync("bash", ["-c", stage.run ?? ""], {
+        encoding: "utf8",
+        env: {
+          ...process.env,
+          GITHUB_WORKSPACE: workspace,
+          PERFORMANCE_HELPER_DIR: helper,
+        },
+      });
+
+      expect(result.status, result.stderr).toBe(0);
+      expect(readFileSync(candidateAction, "utf8")).toBe("trusted action\n");
+      expect(readFileSync(candidateEnsureNode, "utf8")).toBe("trusted script\n");
+    }
+  });
+
   it("pins the OCM release archive and checksum", () => {
     const workflow = readFileSync(WORKFLOW, "utf8");
     const installRun = findStep("Install OCM and Kova").run ?? "";
@@ -425,7 +618,7 @@ describe("OpenClaw performance workflow", () => {
 
     expect(publisher?.needs).toEqual(["resolve_target", "kova", "source_performance"]);
     expect(publisher?.if).toBe(
-      "${{ always() && (github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.publish_reports == true)) && needs.resolve_target.result == 'success' && needs.kova.result != 'cancelled' && needs.source_performance.result != 'cancelled' }}",
+      "${{ always() && needs.resolve_target.outputs.secret_eligible == 'true' && (github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.publish_reports == true)) && needs.resolve_target.result == 'success' && needs.kova.result != 'cancelled' && needs.source_performance.result != 'cancelled' }}",
     );
     expect(publisher?.["runs-on"]).toBe("ubuntu-24.04");
     expect(publisher?.permissions?.actions).toBe("read");
@@ -488,7 +681,7 @@ describe("OpenClaw performance workflow", () => {
 
     expect(appToken.id).toBe("clawgrit_app_token");
     expect(appToken.if).toBe(
-      "${{ steps.prepare.outputs.ready == 'true' && steps.prepare.outputs.already_published != 'true' }}",
+      "${{ needs.resolve_target.outputs.secret_eligible == 'true' && steps.prepare.outputs.ready == 'true' && steps.prepare.outputs.already_published != 'true' }}",
     );
     expect(appToken.uses).toBe(
       "actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1",
@@ -506,7 +699,7 @@ describe("OpenClaw performance workflow", () => {
     expect(workflowText.split(appTokenOutput)).toHaveLength(2);
     expect(workflowText.split("${{ secrets.CLAWSWEEPER_APP_PRIVATE_KEY }}")).toHaveLength(2);
     expect(publish.if).toBe(
-      "${{ steps.prepare.outputs.ready == 'true' && steps.prepare.outputs.already_published != 'true' }}",
+      "${{ needs.resolve_target.outputs.secret_eligible == 'true' && steps.prepare.outputs.ready == 'true' && steps.prepare.outputs.already_published != 'true' }}",
     );
     expect(workflowText).not.toContain("CLAWGRIT_REPORTS_TOKEN");
     expect(workflowText).not.toContain("secrets.GH_APP_PRIVATE_KEY");
@@ -622,7 +815,7 @@ describe("OpenClaw performance workflow", () => {
       "scripts/lib/kova-report-selector.mjs",
     );
     expect(helper.with).toMatchObject({
-      ref: "${{ github.sha }}",
+      ref: "${{ github.workflow_sha }}",
       path: ".artifacts/performance-publisher",
       "sparse-checkout":
         "scripts/lib/kova-report-publish-files.mjs\nscripts/lib/kova-report-selector.mjs\n",
@@ -1110,16 +1303,17 @@ esac
     const runKova = findStep("Run Kova");
 
     expect(configureAuth.if).toContain("matrix.live == 'true'");
+    expect(configureAuth.if).toContain("needs.resolve_target.outputs.secret_eligible == 'true'");
     expect(configureAuth.env?.OPENAI_API_KEY).toBe("${{ secrets.OPENAI_API_KEY }}");
     expect(configureAuth.run).toContain('if [[ -z "${OPENAI_API_KEY:-}" ]]; then');
     expect(configureAuth.run).toContain("cannot run without live evidence");
     expect(configureAuth.run).toContain("exit 1");
     expect(configureAuth.run).not.toContain("will be skipped");
     expect(runKova.env?.OPENAI_API_KEY).toBe(
-      "${{ matrix.live == 'true' && secrets.OPENAI_API_KEY || '' }}",
+      "${{ matrix.live == 'true' && needs.resolve_target.outputs.secret_eligible == 'true' && secrets.OPENAI_API_KEY || '' }}",
     );
     expect(runKova.env?.OPENAI_BASE_URL).toBe(
-      "${{ matrix.live == 'true' && secrets.OPENAI_BASE_URL || '' }}",
+      "${{ matrix.live == 'true' && needs.resolve_target.outputs.secret_eligible == 'true' && secrets.OPENAI_BASE_URL || '' }}",
     );
     expect(runKova.run).not.toContain('echo "skipped=true" >> "$GITHUB_OUTPUT"');
   });

From 15664db855f2163de26e01fab5880e437b65ba8b Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Fri, 21 Aug 2026 07:56:38 -0700
Subject: [PATCH 010/124] refactor(approvals): unify native client setup
 (#127189)

---
 src/infra/exec-approval-surface.test.ts | 54 +++++++++++++++++++++++++
 src/infra/exec-approval-surface.ts      | 51 +++++++++++------------
 2 files changed, 77 insertions(+), 28 deletions(-)

diff --git a/src/infra/exec-approval-surface.test.ts b/src/infra/exec-approval-surface.test.ts
index a0f78af97a94..10f37e3f855c 100644
--- a/src/infra/exec-approval-surface.test.ts
+++ b/src/infra/exec-approval-surface.test.ts
@@ -38,10 +38,14 @@ type ExecApprovalSurfaceModule = typeof import("./exec-approval-surface.js");
 let resolveExecApprovalInitiatingSurfaceState: ExecApprovalSurfaceModule["resolveExecApprovalInitiatingSurfaceState"];
 let resolveApprovalInitiatingSurfaceState: ExecApprovalSurfaceModule["resolveApprovalInitiatingSurfaceState"];
 let supportsNativeExecApprovalClient: ExecApprovalSurfaceModule["supportsNativeExecApprovalClient"];
+let describeNativeExecApprovalClientSetup: ExecApprovalSurfaceModule["describeNativeExecApprovalClientSetup"];
+let describeNativePluginApprovalClientSetup: ExecApprovalSurfaceModule["describeNativePluginApprovalClientSetup"];
 
 describe("resolveExecApprovalInitiatingSurfaceState", () => {
   beforeAll(async () => {
     ({
+      describeNativeExecApprovalClientSetup,
+      describeNativePluginApprovalClientSetup,
       resolveApprovalInitiatingSurfaceState,
       resolveExecApprovalInitiatingSurfaceState,
       supportsNativeExecApprovalClient,
@@ -318,4 +322,54 @@ describe("resolveExecApprovalInitiatingSurfaceState", () => {
 
     expect(supportsNativeExecApprovalClient("matrix")).toBe(true);
   });
+
+  it("routes normalized setup parameters to the selected approval hook", () => {
+    const describeExecApprovalSetup = vi.fn(() => "exec setup");
+    const describePluginApprovalSetup = vi.fn(() => "plugin setup");
+    getChannelPluginMock.mockReturnValue({
+      meta: { label: "Telegram" },
+      approvalCapability: { describeExecApprovalSetup, describePluginApprovalSetup },
+    });
+
+    expect(
+      describeNativeExecApprovalClientSetup({
+        channel: " Telegram ",
+        channelLabel: " Telegram Custom ",
+        accountId: " primary ",
+      }),
+    ).toBe("exec setup");
+    expect(describeExecApprovalSetup).toHaveBeenCalledWith({
+      channel: "telegram",
+      channelLabel: "Telegram Custom",
+      accountId: "primary",
+    });
+
+    expect(describeNativePluginApprovalClientSetup({ channel: " TELEGRAM " })).toBe("plugin setup");
+    expect(describePluginApprovalSetup).toHaveBeenCalledWith({
+      channel: "telegram",
+      channelLabel: "Telegram",
+      accountId: undefined,
+    });
+  });
+
+  it.each([undefined, "web", "tui"])("suppresses setup guidance for %s", (channel) => {
+    expect(describeNativeExecApprovalClientSetup({ channel })).toBeNull();
+    expect(describeNativePluginApprovalClientSetup({ channel })).toBeNull();
+    expect(getChannelPluginMock).not.toHaveBeenCalled();
+  });
+
+  it("does not fall back to the sibling approval hook", () => {
+    const describeExecApprovalSetup = vi.fn(() => "exec setup");
+    const describePluginApprovalSetup = vi.fn(() => "plugin setup");
+    getChannelPluginMock.mockImplementation((channel: string) => ({
+      meta: { label: channel },
+      approvalCapability:
+        channel === "telegram" ? { describePluginApprovalSetup } : { describeExecApprovalSetup },
+    }));
+
+    expect(describeNativeExecApprovalClientSetup({ channel: "telegram" })).toBeNull();
+    expect(describePluginApprovalSetup).not.toHaveBeenCalled();
+    expect(describeNativePluginApprovalClientSetup({ channel: "matrix" })).toBeNull();
+    expect(describeExecApprovalSetup).not.toHaveBeenCalled();
+  });
 });
diff --git a/src/infra/exec-approval-surface.ts b/src/infra/exec-approval-surface.ts
index 76a19260aa20..211e55eee819 100644
--- a/src/infra/exec-approval-surface.ts
+++ b/src/infra/exec-approval-surface.ts
@@ -112,44 +112,39 @@ export function listNativeExecApprovalClientLabels(params?: {
     .toSorted((a, b) => a.localeCompare(b));
 }
 
-/** Returns channel-specific setup guidance for native exec approvals, when available. */
-export function describeNativeExecApprovalClientSetup(params: {
+type NativeApprovalClientSetupParams = {
   channel?: string | null;
   channelLabel?: string | null;
   accountId?: string | null;
-}): string | null {
+};
+
+function describeNativeApprovalClientSetup(
+  params: NativeApprovalClientSetupParams,
+  approvalKind: ChannelApprovalKind,
+): string | null {
   const channel = normalizeMessageChannel(params.channel);
   if (!channel || channel === INTERNAL_MESSAGE_CHANNEL || channel === "tui") {
     return null;
   }
   const channelLabel = normalizeOptionalString(params.channelLabel) ?? labelForChannel(channel);
   const accountId = normalizeOptionalString(params.accountId);
-  return (
-    resolveChannelApprovalCapability(getChannelPlugin(channel))?.describeExecApprovalSetup?.({
-      channel,
-      channelLabel,
-      accountId,
-    }) ?? null
-  );
+  const capability = resolveChannelApprovalCapability(getChannelPlugin(channel));
+  const setupParams = { channel, channelLabel, accountId };
+  return approvalKind === "exec"
+    ? (capability?.describeExecApprovalSetup?.(setupParams) ?? null)
+    : (capability?.describePluginApprovalSetup?.(setupParams) ?? null);
+}
+
+/** Returns channel-specific setup guidance for native exec approvals, when available. */
+export function describeNativeExecApprovalClientSetup(
+  params: NativeApprovalClientSetupParams,
+): string | null {
+  return describeNativeApprovalClientSetup(params, "exec");
 }
 
 /** Returns channel-specific setup guidance for native plugin approvals, when available. */
-export function describeNativePluginApprovalClientSetup(params: {
-  channel?: string | null;
-  channelLabel?: string | null;
-  accountId?: string | null;
-}): string | null {
-  const channel = normalizeMessageChannel(params.channel);
-  if (!channel || channel === INTERNAL_MESSAGE_CHANNEL || channel === "tui") {
-    return null;
-  }
-  const channelLabel = normalizeOptionalString(params.channelLabel) ?? labelForChannel(channel);
-  const accountId = normalizeOptionalString(params.accountId);
-  return (
-    resolveChannelApprovalCapability(getChannelPlugin(channel))?.describePluginApprovalSetup?.({
-      channel,
-      channelLabel,
-      accountId,
-    }) ?? null
-  );
+export function describeNativePluginApprovalClientSetup(
+  params: NativeApprovalClientSetupParams,
+): string | null {
+  return describeNativeApprovalClientSetup(params, "plugin");
 }

From 3ae7ba319461c00aba59e0d1b74df0ac0e21f45e Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 08:13:49 -0700
Subject: [PATCH 011/124] fix(ui): copy Lobsterdex links through clipboard
 fallback (#127194)

Amp-Thread-ID: https://ampcode.com/threads/T-01a021f4-b547-7788-a916-d4a94cbd3e3b

Co-authored-by: Amp <amp@ampcode.com>
---
 .../lobsterdex/lobsterdex-page.e2e.test.ts    | 196 ++++++++++++++++++
 ui/src/pages/lobsterdex/lobsterdex-page.ts    |  31 ++-
 ui/src/pages/lobsterdex/view.ts               |  15 +-
 3 files changed, 229 insertions(+), 13 deletions(-)
 create mode 100644 ui/src/pages/lobsterdex/lobsterdex-page.e2e.test.ts

diff --git a/ui/src/pages/lobsterdex/lobsterdex-page.e2e.test.ts b/ui/src/pages/lobsterdex/lobsterdex-page.e2e.test.ts
new file mode 100644
index 000000000000..92460e2a3160
--- /dev/null
+++ b/ui/src/pages/lobsterdex/lobsterdex-page.e2e.test.ts
@@ -0,0 +1,196 @@
+import { expect, it } from "vitest";
+import { createControlUiE2eSuite } from "../../e2e/control-ui-e2e-suite.test-support.ts";
+import { installMockGateway } from "../../test-helpers/control-ui-e2e.ts";
+
+type ClipboardFaultState = {
+  asyncWrites: string[];
+  execSucceeds: boolean;
+  legacyWrites: string[];
+  mode: "defer" | "missing" | "reject";
+  pendingRejects: Array<(reason?: unknown) => void>;
+};
+
+const suite = createControlUiE2eSuite({
+  name: "Control UI Lobsterdex clipboard E2E",
+  startServerBeforeBrowser: true,
+  unavailableMessage: (executablePath) =>
+    `Playwright Chromium is not available at ${executablePath}`,
+});
+
+suite.define(() => {
+  it("falls back, announces failure, and keeps feedback with the newest copy", async () => {
+    await suite.withPage(
+      {
+        hasTouch: true,
+        locale: "en-US",
+        serviceWorkers: "block",
+        viewport: { height: 844, width: 390 },
+      },
+      async ({ page }) => {
+        await page.addInitScript(() => {
+          const state: ClipboardFaultState = {
+            asyncWrites: [],
+            execSucceeds: true,
+            legacyWrites: [],
+            mode: "reject",
+            pendingRejects: [],
+          };
+          Object.defineProperty(window, "lobsterdexClipboardFault", { value: state });
+          Object.defineProperty(navigator, "clipboard", {
+            configurable: true,
+            get: () =>
+              state.mode === "missing"
+                ? undefined
+                : {
+                    writeText(text: string) {
+                      state.asyncWrites.push(text);
+                      if (state.mode === "reject") {
+                        return Promise.reject(
+                          new DOMException("Clipboard access denied", "NotAllowedError"),
+                        );
+                      }
+                      return new Promise<void>((_resolve, reject) => {
+                        state.pendingRejects.push(reject);
+                      });
+                    },
+                  },
+          });
+          document.execCommand = (command: string) => {
+            if (command !== "copy") {
+              return false;
+            }
+            state.legacyWrites.push(
+              document.querySelector<HTMLTextAreaElement>("textarea")?.value ?? "",
+            );
+            return state.execSucceeds;
+          };
+        });
+        const gateway = await installMockGateway(page);
+        const response = await page.goto(`${suite.server.baseUrl}settings/lobsterdex`);
+        expect(response?.status()).toBe(200);
+
+        const pageRoot = page.locator("openclaw-lobsterdex-page");
+        const copyButtons = pageRoot.getByRole("button", { name: "Copy link" });
+        await expect.poll(() => copyButtons.count()).toBeGreaterThan(1);
+        const crimson = copyButtons.nth(0);
+        const blue = copyButtons.nth(1);
+        const crimsonUrl = `${new URL(suite.server.baseUrl).origin}/settings/lobsterdex#lobsterdex-crimson`;
+        const blueUrl = `${new URL(suite.server.baseUrl).origin}/settings/lobsterdex#lobsterdex-blue`;
+        const requestsBeforeCopy = (await gateway.getRequests()).length;
+
+        await crimson.focus();
+        await page.keyboard.press("Enter");
+        await expect
+          .poll(() =>
+            page.evaluate(
+              () =>
+                (window as typeof window & { lobsterdexClipboardFault: ClipboardFaultState })
+                  .lobsterdexClipboardFault,
+            ),
+          )
+          .toMatchObject({ asyncWrites: [crimsonUrl], legacyWrites: [crimsonUrl] });
+
+        await page.evaluate(() => {
+          (
+            window as typeof window & { lobsterdexClipboardFault: ClipboardFaultState }
+          ).lobsterdexClipboardFault.mode = "missing";
+        });
+        await blue.tap();
+        await expect
+          .poll(() =>
+            page.evaluate(
+              () =>
+                (window as typeof window & { lobsterdexClipboardFault: ClipboardFaultState })
+                  .lobsterdexClipboardFault,
+            ),
+          )
+          .toMatchObject({ asyncWrites: [crimsonUrl], legacyWrites: [crimsonUrl, blueUrl] });
+
+        await page.evaluate(() => {
+          const state = (
+            window as typeof window & { lobsterdexClipboardFault: ClipboardFaultState }
+          ).lobsterdexClipboardFault;
+          state.mode = "reject";
+          state.execSucceeds = false;
+        });
+        await crimson.tap();
+        await expect.poll(() => pageRoot.getByRole("alert").textContent()).toBe("Copy failed");
+        await pageRoot.evaluate((element) => {
+          const parent = element.parentElement;
+          if (!parent) {
+            throw new Error("Lobsterdex page has no route host");
+          }
+          element.remove();
+          parent.append(element);
+        });
+        await expect.poll(() => pageRoot.getByRole("alert").count()).toBe(0);
+
+        await page.evaluate(() => {
+          const state = (
+            window as typeof window & { lobsterdexClipboardFault: ClipboardFaultState }
+          ).lobsterdexClipboardFault;
+          state.mode = "defer";
+          state.execSucceeds = true;
+          state.asyncWrites = [];
+          state.legacyWrites = [];
+          state.pendingRejects = [];
+        });
+        await crimson.focus();
+        await page.keyboard.press("Enter");
+        await blue.tap();
+        await expect
+          .poll(() =>
+            page.evaluate(
+              () =>
+                (window as typeof window & { lobsterdexClipboardFault: ClipboardFaultState })
+                  .lobsterdexClipboardFault.pendingRejects.length,
+            ),
+          )
+          .toBe(2);
+        expect(await pageRoot.getByRole("alert").count()).toBe(0);
+
+        await page.evaluate(() => {
+          const state = (
+            window as typeof window & { lobsterdexClipboardFault: ClipboardFaultState }
+          ).lobsterdexClipboardFault;
+          state.pendingRejects[1]?.(new DOMException("Newer write rejected", "NotAllowedError"));
+        });
+        await blue.locator('path[d="M20 6 9 17l-5-5"]').waitFor();
+        expect(await crimson.locator('path[d="M20 6 9 17l-5-5"]').count()).toBe(0);
+        await expect
+          .poll(() =>
+            page.evaluate(
+              () =>
+                (window as typeof window & { lobsterdexClipboardFault: ClipboardFaultState })
+                  .lobsterdexClipboardFault.legacyWrites,
+            ),
+          )
+          .toEqual([blueUrl]);
+
+        await page.evaluate(() => {
+          const state = (
+            window as typeof window & { lobsterdexClipboardFault: ClipboardFaultState }
+          ).lobsterdexClipboardFault;
+          state.pendingRejects[0]?.(new DOMException("Older write rejected", "NotAllowedError"));
+        });
+        await page.evaluate(
+          () =>
+            new Promise<void>((resolve) => {
+              window.setTimeout(resolve, 0);
+            }),
+        );
+        expect(await crimson.locator('path[d="M20 6 9 17l-5-5"]').count()).toBe(0);
+        expect(await blue.locator('path[d="M20 6 9 17l-5-5"]').count()).toBe(1);
+        expect(
+          await page.evaluate(
+            () =>
+              (window as typeof window & { lobsterdexClipboardFault: ClipboardFaultState })
+                .lobsterdexClipboardFault.legacyWrites,
+          ),
+        ).toEqual([blueUrl]);
+        await expect.poll(() => blue.locator('path[d="M20 6 9 17l-5-5"]').count()).toBe(0);
+        expect((await gateway.getRequests()).length).toBe(requestsBeforeCopy);
+      },
+    );
+  });
+});
diff --git a/ui/src/pages/lobsterdex/lobsterdex-page.ts b/ui/src/pages/lobsterdex/lobsterdex-page.ts
index 22798f196289..1ccef5c766c0 100644
--- a/ui/src/pages/lobsterdex/lobsterdex-page.ts
+++ b/ui/src/pages/lobsterdex/lobsterdex-page.ts
@@ -5,14 +5,18 @@ import { getLobsterdexEntries } from "../../components/lobster-dex.ts";
 import type { LobsterPetPaletteId } from "../../components/lobster-pet-contract.ts";
 import { LOBSTER_PET_PALETTES } from "../../components/lobster-pet.ts";
 import { renderSettingsWorkspace } from "../../components/settings-workspace.ts";
+import { copyToClipboard } from "../../lib/clipboard.ts";
 import { OpenClawLightDomElement } from "../../lit/openclaw-element.ts";
-import { renderLobsterdex } from "./view.ts";
+import { renderLobsterdex, type LobsterdexCopyFeedback } from "./view.ts";
 
 class LobsterdexPage extends OpenClawLightDomElement {
-  @state() private copiedPaletteId: LobsterPetPaletteId | null = null;
+  @state() private copyFeedback: LobsterdexCopyFeedback | null = null;
+  private copyAttempt = 0;
   private copyResetTimer: number | null = null;
 
   override disconnectedCallback(): void {
+    this.copyAttempt += 1;
+    this.copyFeedback = null;
     if (this.copyResetTimer !== null) {
       window.clearTimeout(this.copyResetTimer);
       this.copyResetTimer = null;
@@ -54,18 +58,23 @@ class LobsterdexPage extends OpenClawLightDomElement {
   }
 
   private readonly copyLink = async (paletteId: LobsterPetPaletteId): Promise<void> => {
-    const url = `${location.origin}${location.pathname}#lobsterdex-${paletteId}`;
-    try {
-      await navigator.clipboard.writeText(url);
-    } catch {
-      return;
-    }
-    this.copiedPaletteId = paletteId;
+    const attempt = ++this.copyAttempt;
+    this.copyFeedback = null;
     if (this.copyResetTimer !== null) {
       window.clearTimeout(this.copyResetTimer);
+      this.copyResetTimer = null;
     }
+    const url = `${location.origin}${location.pathname}#lobsterdex-${paletteId}`;
+    const copied = await copyToClipboard(
+      url,
+      () => this.isConnected && attempt === this.copyAttempt,
+    );
+    if (!this.isConnected || attempt !== this.copyAttempt) {
+      return;
+    }
+    this.copyFeedback = { paletteId, status: copied ? "copied" : "error" };
     this.copyResetTimer = window.setTimeout(() => {
-      this.copiedPaletteId = null;
+      this.copyFeedback = null;
       this.copyResetTimer = null;
     }, 1_500);
   };
@@ -77,7 +86,7 @@ class LobsterdexPage extends OpenClawLightDomElement {
       </section>
       ${renderSettingsWorkspace(
         renderLobsterdex(getLobsterdexEntries(), {
-          copiedPaletteId: this.copiedPaletteId,
+          copyFeedback: this.copyFeedback,
           onCopyLink: (paletteId) => void this.copyLink(paletteId),
         }),
       )}
diff --git a/ui/src/pages/lobsterdex/view.ts b/ui/src/pages/lobsterdex/view.ts
index 3b5dd4804c36..5208aca972b4 100644
--- a/ui/src/pages/lobsterdex/view.ts
+++ b/ui/src/pages/lobsterdex/view.ts
@@ -20,8 +20,13 @@ type LobsterdexViewEntry = {
 
 type LobsterdexViewEntries = ReadonlyMap<string, LobsterdexViewEntry>;
 
+export type LobsterdexCopyFeedback = {
+  paletteId: LobsterPetPaletteId;
+  status: "copied" | "error";
+};
+
 type LobsterdexViewProps = {
-  copiedPaletteId?: LobsterPetPaletteId | null;
+  copyFeedback?: LobsterdexCopyFeedback | null;
   onCopyLink?: (paletteId: LobsterPetPaletteId) => void;
 };
 
@@ -47,6 +52,9 @@ export function renderLobsterdex(entries: LobsterdexViewEntries, props: Lobsterd
         </div>
         <span class="lobsterdex-page__count">${countLabel}</span>
       </header>
+      ${props.copyFeedback?.status === "error"
+        ? html`<div class="callout danger" role="alert">${t("common.copyFailed")}</div>`
+        : nothing}
       <div class="lobsterdex-page__grid" aria-label=${countLabel}>
         ${LOBSTER_PET_PALETTES.map((palette) => {
           const look = canonicalLobsterLook(palette);
@@ -78,7 +86,10 @@ export function renderLobsterdex(entries: LobsterdexViewEntries, props: Lobsterd
                 @click=${() => props.onCopyLink?.(palette.id)}
               >
                 <span aria-hidden="true"
-                  >${props.copiedPaletteId === palette.id ? icons.check : icons.link}</span
+                  >${props.copyFeedback?.status === "copied" &&
+                  props.copyFeedback.paletteId === palette.id
+                    ? icons.check
+                    : icons.link}</span
                 >
               </button>
               <div

From a5bac03e514d06033f99d3c4b6cb9b78fc268c17 Mon Sep 17 00:00:00 2001
From: Shakker <shakkerdroid@gmail.com>
Date: Fri, 21 Aug 2026 15:59:17 +0100
Subject: [PATCH 012/124] fix: preserve Codex compaction activity

---
 CHANGELOG.md                                  |  1 +
 .../app-server/context-compaction-activity.ts | 73 +++++++++++++++++++
 .../codex/src/app-server/event-projector.ts   |  8 ++
 packages/agent-core/src/harness/messages.ts   |  3 +
 packages/agent-core/src/types.ts              |  2 +
 ui/src/pages/chat/chat-progress.ts            | 20 +++++
 ui/src/pages/chat/chat-thread-build.ts        |  3 +-
 ui/src/pages/chat/chat-thread-grouping.ts     |  4 +
 8 files changed, 113 insertions(+), 1 deletion(-)
 create mode 100644 extensions/codex/src/app-server/context-compaction-activity.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 22cc4481d5e9..d3a1eff86560 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -69,6 +69,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- **Control UI Codex compaction history:** preserve successful native context compactions as durable, model-excluded activity inside completed work traces after the composer status clears or the session reloads. Fixes #127206. Thanks @shakkernerd.
 - **Control UI Codex steering:** preserve pre-steer commentary and tool activity in durable transcript order, keep it visible while active, and collapse it before the steering message after completion. Fixes #126938. Thanks @shakkernerd.
 - **Onboarding migration menu:** group Claude, Codex, Hermes, and plugin-provided imports under a single **Import from another agent** setup choice while preserving detected source hints, manual paths, and Back navigation before import begins. Fixes #126440. Thanks @shakkernerd.
 - **Onboarding provider hook loading:** scope selected-model hook fallback to the chosen provider so metadata-only setup providers do not load unrelated plugins before configuration completes. Fixes #126408. Thanks @shakkernerd.
diff --git a/extensions/codex/src/app-server/context-compaction-activity.ts b/extensions/codex/src/app-server/context-compaction-activity.ts
new file mode 100644
index 000000000000..8ce22be5a6ec
--- /dev/null
+++ b/extensions/codex/src/app-server/context-compaction-activity.ts
@@ -0,0 +1,73 @@
+import {
+  embeddedAgentLog,
+  formatErrorMessage,
+  type EmbeddedRunAttemptParamsV2 as EmbeddedRunAttemptParams,
+} from "openclaw/plugin-sdk/agent-harness-runtime";
+import {
+  appendSessionTranscriptMessageByIdentity,
+  publishSessionTranscriptUpdateByIdentity,
+} from "openclaw/plugin-sdk/session-transcript-runtime";
+
+const CONTEXT_COMPACTION_CUSTOM_TYPE = "openclaw.context-compaction";
+
+export async function persistCodexContextCompactionActivity(params: {
+  run: EmbeddedRunAttemptParams;
+  threadId: string;
+  turnId: string;
+  itemId: string;
+  timestamp: number;
+}): Promise<void> {
+  const target = params.run.sessionTarget;
+  if (!target?.sessionId || !target.sessionKey || !target.storePath) {
+    return;
+  }
+  const activityId = `codex-context-compaction:${params.threadId}:${params.turnId}:${params.itemId}`;
+  const message = {
+    role: "custom" as const,
+    customType: CONTEXT_COMPACTION_CUSTOM_TYPE,
+    content: "Context compacted",
+    display: true,
+    excludeFromContext: true,
+    details: {
+      kind: "context_compaction",
+      backend: "codex-app-server",
+      threadId: params.threadId,
+      turnId: params.turnId,
+      itemId: params.itemId,
+      runId: params.run.runId,
+    },
+    timestamp: params.timestamp,
+    idempotencyKey: activityId,
+  };
+  try {
+    const appended = await appendSessionTranscriptMessageByIdentity({
+      agentId: target.agentId,
+      sessionId: target.sessionId,
+      sessionKey: target.sessionKey,
+      storePath: target.storePath,
+      config: params.run.config,
+      cwd: params.run.workspaceDir,
+      eventId: activityId,
+      message,
+    });
+    if (!appended?.appended) {
+      return;
+    }
+    await publishSessionTranscriptUpdateByIdentity({
+      agentId: target.agentId,
+      sessionId: target.sessionId,
+      sessionKey: target.sessionKey,
+      storePath: target.storePath,
+      update: {
+        message: appended.message,
+        messageId: appended.messageId,
+        runId: params.run.runId,
+      },
+    });
+  } catch (error) {
+    embeddedAgentLog.warn("failed to persist codex context compaction activity", {
+      error: formatErrorMessage(error),
+      itemId: params.itemId,
+    });
+  }
+}
diff --git a/extensions/codex/src/app-server/event-projector.ts b/extensions/codex/src/app-server/event-projector.ts
index b4b7da7f862f..6fab913ef4b7 100644
--- a/extensions/codex/src/app-server/event-projector.ts
+++ b/extensions/codex/src/app-server/event-projector.ts
@@ -10,6 +10,7 @@ import {
 } from "openclaw/plugin-sdk/agent-harness-runtime";
 import { readStringField as readString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import type { AttemptFailureSource, EmbeddedRunAttemptResult } from "./attempt-terminal.js";
+import { persistCodexContextCompactionActivity } from "./context-compaction-activity.js";
 import { CodexAssistantProjection } from "./event-projector-assistant.js";
 import { CodexProjectionDiagnostics } from "./event-projector-diagnostics.js";
 import { CodexEventProjection } from "./event-projector-events.js";
@@ -520,6 +521,13 @@ export class CodexAppServerEventProjector {
           channelId: this.params.messageChannel ?? this.params.messageProvider ?? undefined,
         },
       });
+      await persistCodexContextCompactionActivity({
+        run: this.params,
+        threadId: this.threadId,
+        turnId: this.turnId,
+        itemId,
+        timestamp: this.nextTranscriptTimestamp(),
+      });
       this.emitCompactionEnd(itemId, true);
     }
     this.toolProgressProjection.recordToolMeta(item);
diff --git a/packages/agent-core/src/harness/messages.ts b/packages/agent-core/src/harness/messages.ts
index eec60e55fab0..076b878d928e 100644
--- a/packages/agent-core/src/harness/messages.ts
+++ b/packages/agent-core/src/harness/messages.ts
@@ -143,6 +143,9 @@ export function convertToLlm(messages: AgentMessage[]): Message[] {
             timestamp: message.timestamp,
           };
         case "custom": {
+          if (message.excludeFromContext) {
+            return undefined;
+          }
           const content =
             typeof message.content === "string"
               ? [{ type: "text" as const, text: message.content }]
diff --git a/packages/agent-core/src/types.ts b/packages/agent-core/src/types.ts
index 45534bffa79c..6cbaac6fc8bc 100644
--- a/packages/agent-core/src/types.ts
+++ b/packages/agent-core/src/types.ts
@@ -427,6 +427,8 @@ export interface CustomMessage<T = unknown> {
   content: string | (TextContent | ImageContent)[];
   /** Whether UI surfaces should display this message. */
   display: boolean;
+  /** Keep display-only application activity out of future model context. */
+  excludeFromContext?: boolean;
   /** Optional application-specific metadata. */
   details?: T;
   /** Millisecond timestamp for transcript ordering. */
diff --git a/ui/src/pages/chat/chat-progress.ts b/ui/src/pages/chat/chat-progress.ts
index 7d136ee11ad4..868cafd27074 100644
--- a/ui/src/pages/chat/chat-progress.ts
+++ b/ui/src/pages/chat/chat-progress.ts
@@ -1,3 +1,4 @@
+import { asNullableRecord as asRecord } from "@openclaw/normalization-core/record-coerce";
 import { t } from "../../i18n/index.ts";
 import type { ChatItem, ChatQueueItem } from "../../lib/chat/chat-types.ts";
 import { formatCompactTokenCount } from "../../lib/format.ts";
@@ -11,6 +12,25 @@ type WorkingProgressCache = WorkingProgress & {
   runId: string | null;
 };
 
+const CONTEXT_COMPACTION_CUSTOM_TYPE = "openclaw.context-compaction";
+
+export function projectContextCompactionActivity(message: unknown): unknown {
+  const record = asRecord(message);
+  if (record?.role !== "custom" || record.customType !== CONTEXT_COMPACTION_CUSTOM_TYPE) {
+    return message;
+  }
+  const metadata = asRecord(record["__openclaw"]);
+  return {
+    ...record,
+    role: "assistant",
+    content: [{ type: "text", text: t("chat.composer.contextCompacted") }],
+    __openclaw: {
+      ...metadata,
+      runtimeActivityKind: "context_compaction",
+    },
+  };
+}
+
 const workingProgressBySession = new Map<string, WorkingProgressCache>();
 let anonymousWorkingProgressId = 0;
 
diff --git a/ui/src/pages/chat/chat-thread-build.ts b/ui/src/pages/chat/chat-thread-build.ts
index 9a2600691fc4..c8668e9f657f 100644
--- a/ui/src/pages/chat/chat-thread-build.ts
+++ b/ui/src/pages/chat/chat-thread-build.ts
@@ -24,6 +24,7 @@ import {
   buildCompactionDividerItem,
   buildResetDividerItem,
   clearWorkingProgress,
+  projectContextCompactionActivity,
   resolveWorkingProgress,
   shouldRenderQueuedSendInThread,
 } from "./chat-progress.ts";
@@ -214,7 +215,7 @@ export function buildChatItems(props: BuildChatItemsProps): Array<ChatItem | Mes
     }
   }
   for (let i = 0; i < history.length; i++) {
-    const msg = history[i];
+    const msg = projectContextCompactionActivity(history[i]);
     const itemKey = historyKeys[i] ?? messageKey(msg, i);
     const normalized = safeNormalizeMessage(msg);
     if (!normalized) {
diff --git a/ui/src/pages/chat/chat-thread-grouping.ts b/ui/src/pages/chat/chat-thread-grouping.ts
index 7c682c412bf2..d1e4ecfa5ce7 100644
--- a/ui/src/pages/chat/chat-thread-grouping.ts
+++ b/ui/src/pages/chat/chat-thread-grouping.ts
@@ -542,6 +542,10 @@ export function assistantGroupCanOwnActiveRunStatus(group: MessageGroup): boolea
   return (
     group.role.toLowerCase() === "assistant" &&
     !assistantGroupIsForwardedBoundary(group) &&
+    !group.messages.every(
+      ({ message }) =>
+        asRecord(asRecord(message)?.["__openclaw"])?.runtimeActivityKind === "context_compaction",
+    ) &&
     groupHasVisibleReplyContent(group)
   );
 }

From 7b5430a2d3937756435620eea88ea3cd3d19f53b Mon Sep 17 00:00:00 2001
From: Shakker <shakkerdroid@gmail.com>
Date: Fri, 21 Aug 2026 16:03:06 +0100
Subject: [PATCH 013/124] test: cover durable compaction activity

---
 .../context-compaction-activity.test.ts       | 70 +++++++++++++++++++
 .../harness/session/session-context.test.ts   | 13 ++++
 ui/src/pages/chat/chat-thread-grouping.ts     | 15 ++--
 ui/src/pages/chat/chat-thread.test.ts         | 29 ++++++++
 4 files changed, 123 insertions(+), 4 deletions(-)
 create mode 100644 extensions/codex/src/app-server/context-compaction-activity.test.ts

diff --git a/extensions/codex/src/app-server/context-compaction-activity.test.ts b/extensions/codex/src/app-server/context-compaction-activity.test.ts
new file mode 100644
index 000000000000..49bb90d820e0
--- /dev/null
+++ b/extensions/codex/src/app-server/context-compaction-activity.test.ts
@@ -0,0 +1,70 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { persistCodexContextCompactionActivity } from "./context-compaction-activity.js";
+
+const appendMessage = vi.hoisted(() => vi.fn());
+const publishUpdate = vi.hoisted(() => vi.fn());
+
+vi.mock("openclaw/plugin-sdk/session-transcript-runtime", () => ({
+  appendSessionTranscriptMessageByIdentity: appendMessage,
+  publishSessionTranscriptUpdateByIdentity: publishUpdate,
+}));
+
+beforeEach(() => {
+  appendMessage.mockReset();
+  publishUpdate.mockReset();
+});
+
+describe("persistCodexContextCompactionActivity", () => {
+  it("publishes one model-excluded activity and leaves replay deduplication to transcript identity", async () => {
+    appendMessage
+      .mockImplementationOnce(async (params: { message: unknown }) => ({
+        appended: true,
+        message: params.message,
+        messageId: "activity-message",
+      }))
+      .mockResolvedValueOnce({
+        appended: false,
+        message: {},
+        messageId: "activity-message",
+      });
+    const params = {
+      run: {
+        runId: "run-1",
+        workspaceDir: "/workspace",
+        sessionTarget: {
+          agentId: "main",
+          sessionId: "session-1",
+          sessionKey: "agent:main:dashboard:session-1",
+          storePath: "/state/openclaw-agent.sqlite",
+        },
+      },
+      threadId: "thread-1",
+      turnId: "turn-1",
+      itemId: "compact-1",
+      timestamp: 123,
+    } as Parameters<typeof persistCodexContextCompactionActivity>[0];
+
+    await persistCodexContextCompactionActivity(params);
+    await persistCodexContextCompactionActivity(params);
+
+    expect(appendMessage).toHaveBeenCalledTimes(2);
+    expect(appendMessage.mock.calls[0]?.[0]).toMatchObject({
+      eventId: "codex-context-compaction:thread-1:turn-1:compact-1",
+      message: {
+        role: "custom",
+        customType: "openclaw.context-compaction",
+        content: "Context compacted",
+        display: true,
+        excludeFromContext: true,
+        idempotencyKey: "codex-context-compaction:thread-1:turn-1:compact-1",
+      },
+    });
+    expect(publishUpdate).toHaveBeenCalledOnce();
+    expect(publishUpdate.mock.calls[0]?.[0]).toMatchObject({
+      update: {
+        messageId: "activity-message",
+        runId: "run-1",
+      },
+    });
+  });
+});
diff --git a/packages/agent-core/src/harness/session/session-context.test.ts b/packages/agent-core/src/harness/session/session-context.test.ts
index 412f32837eaf..176cddee30b0 100644
--- a/packages/agent-core/src/harness/session/session-context.test.ts
+++ b/packages/agent-core/src/harness/session/session-context.test.ts
@@ -133,6 +133,19 @@ function toolResultEntry(
 }
 
 describe("buildSessionContext", () => {
+  it("keeps display-only custom activity out of model input", () => {
+    const activity = {
+      role: "custom" as const,
+      customType: "openclaw.context-compaction",
+      content: "Context compacted",
+      display: true,
+      excludeFromContext: true,
+      timestamp: Date.parse(timestamp),
+    };
+
+    expect(convertToLlm([activity])).toEqual([]);
+  });
+
   it("keeps private shell executions in history without projecting them into context", () => {
     const hiddenEntry = bashEntry("hidden", "initial", "private shell output", true);
     const visibleEntry = bashEntry("visible", "hidden", "visible shell output", false);
diff --git a/ui/src/pages/chat/chat-thread-grouping.ts b/ui/src/pages/chat/chat-thread-grouping.ts
index d1e4ecfa5ce7..64236e2a5ba4 100644
--- a/ui/src/pages/chat/chat-thread-grouping.ts
+++ b/ui/src/pages/chat/chat-thread-grouping.ts
@@ -86,12 +86,18 @@ export function groupMessages(items: ChatItem[]): Array<ChatItem | MessageGroup>
       currentGroup?.role === "assistant" &&
       isKeyedAssistantStreamFallbackMessage(currentGroup.messages[0]?.message) !==
         isKeyedAssistantStreamFallbackMessage(item.message);
+    const splitsRuntimeActivity =
+      role === "assistant" &&
+      currentGroup?.role === "assistant" &&
+      isContextCompactionActivity(currentGroup.messages[0]?.message) !==
+        isContextCompactionActivity(item.message);
 
     if (
       !currentGroup ||
       startsProjectedTurn ||
       currentGroup.role !== role ||
       splitsAssistantCommentary ||
+      splitsRuntimeActivity ||
       (shouldSplitBySender &&
         (currentGroup.senderLabel !== senderLabel ||
           senderIdentityKey(currentGroup.sender) !== senderIdentityKey(sender)))
@@ -542,14 +548,15 @@ export function assistantGroupCanOwnActiveRunStatus(group: MessageGroup): boolea
   return (
     group.role.toLowerCase() === "assistant" &&
     !assistantGroupIsForwardedBoundary(group) &&
-    !group.messages.every(
-      ({ message }) =>
-        asRecord(asRecord(message)?.["__openclaw"])?.runtimeActivityKind === "context_compaction",
-    ) &&
+    !group.messages.every(({ message }) => isContextCompactionActivity(message)) &&
     groupHasVisibleReplyContent(group)
   );
 }
 
+function isContextCompactionActivity(message: unknown): boolean {
+  return asRecord(asRecord(message)?.["__openclaw"])?.runtimeActivityKind === "context_compaction";
+}
+
 // History carries no final-vs-commentary marker (commentary exists only as
 // live stream segments), so the last assistant group with visible content
 // stands in for the final reply. Turns whose last content is commentary
diff --git a/ui/src/pages/chat/chat-thread.test.ts b/ui/src/pages/chat/chat-thread.test.ts
index 8c7154e12a7f..93919ac98e0f 100644
--- a/ui/src/pages/chat/chat-thread.test.ts
+++ b/ui/src/pages/chat/chat-thread.test.ts
@@ -757,6 +757,35 @@ describe("collapseCompletedTurnWork", () => {
     expect(requireGroup(items[2]).role).toBe("assistant");
   });
 
+  it("keeps durable context compaction inside completed work instead of treating it as the reply", () => {
+    const items = collapsedItems({
+      messages: [
+        userMessage("do it", 1_000),
+        {
+          role: "custom",
+          customType: "openclaw.context-compaction",
+          content: "Context compacted",
+          display: true,
+          excludeFromContext: true,
+          timestamp: 2_000,
+        },
+        assistantMessage("All done.", 3_000),
+      ],
+    });
+
+    expect(items.map((item) => item.kind)).toEqual(["group", "work-group", "group"]);
+    const work = requireWorkGroup(items[1]);
+    expect(work.groups).toHaveLength(1);
+    expect(work.groups[0]?.messages[0]?.message).toMatchObject({
+      role: "assistant",
+      content: [{ type: "text", text: "Context compacted" }],
+      __openclaw: { runtimeActivityKind: "context_compaction" },
+    });
+    expect(requireGroup(items[2]).messages[0]?.message).toMatchObject({
+      content: "All done.",
+    });
+  });
+
   it.each([
     {
       role: "assistant",

From f65b7e06eaa66b9ce5fe2b3ca3549fbb7834acaa Mon Sep 17 00:00:00 2001
From: Shakker <shakkerdroid@gmail.com>
Date: Fri, 21 Aug 2026 16:08:26 +0100
Subject: [PATCH 014/124] fix: persist manual Codex compactions (#127230)

---
 extensions/codex/src/app-server/compact.ts    | 22 +++++++++++++++++--
 .../context-compaction-activity.test.ts       | 16 ++++++--------
 .../app-server/context-compaction-activity.ts | 15 ++++++++-----
 .../codex/src/app-server/event-projector.ts   |  5 ++++-
 4 files changed, 40 insertions(+), 18 deletions(-)

diff --git a/extensions/codex/src/app-server/compact.ts b/extensions/codex/src/app-server/compact.ts
index 2309e3c06ea0..bd516c0b80be 100644
--- a/extensions/codex/src/app-server/compact.ts
+++ b/extensions/codex/src/app-server/compact.ts
@@ -32,6 +32,7 @@ import {
   type CodexAppServerLiveThreadOwnership,
 } from "./client-runtime.js";
 import { CodexAppServerRpcError, type CodexAppServerClient } from "./client.js";
+import { persistCodexContextCompactionActivity } from "./context-compaction-activity.js";
 import { readCodexThreadContextSnapshot } from "./event-projector-usage.js";
 import {
   readCodexNotificationThreadId,
@@ -70,7 +71,7 @@ type CodexAppServerCompactOptions = {
 };
 
 type CodexNativeCompactionCompletion =
-  | { completed: true; tokensAfter?: number }
+  | { completed: true; turnId?: string; itemId?: string; tokensAfter?: number }
   | { completed: false; reason: string };
 
 function watchCodexNativeCompactionCompletion(params: {
@@ -111,7 +112,12 @@ function watchCodexNativeCompactionCompletion(params: {
     resolveCompletion(result);
   };
   const complete = () =>
-    finish({ completed: true, ...(tokensAfter !== undefined ? { tokensAfter } : {}) });
+    finish({
+      completed: true,
+      ...(compactionTurnId ? { turnId: compactionTurnId } : {}),
+      ...(compactionItemId ? { itemId: compactionItemId } : {}),
+      ...(tokensAfter !== undefined ? { tokensAfter } : {}),
+    });
   const fail = (reason: string) => finish({ completed: false, reason });
   const retireUnconfirmed = (reason: string) => {
     if (settled || retirementStarted) {
@@ -742,6 +748,18 @@ async function compactCodexNativeThread(
             throw new Error(completion.reason);
           }
           tokensAfter = completion.tokensAfter;
+          if (completion.turnId && completion.itemId) {
+            await persistCodexContextCompactionActivity({
+              sessionTarget: params.sessionTarget,
+              config: params.config,
+              cwd: params.workspaceDir,
+              runId: params.runId,
+              threadId: binding.threadId,
+              turnId: completion.turnId,
+              itemId: completion.itemId,
+              timestamp: Date.now(),
+            });
+          }
           embeddedAgentLog.info("completed codex app-server compaction", {
             sessionId: params.sessionId,
             threadId: binding.threadId,
diff --git a/extensions/codex/src/app-server/context-compaction-activity.test.ts b/extensions/codex/src/app-server/context-compaction-activity.test.ts
index 49bb90d820e0..19e7a03d5c02 100644
--- a/extensions/codex/src/app-server/context-compaction-activity.test.ts
+++ b/extensions/codex/src/app-server/context-compaction-activity.test.ts
@@ -28,15 +28,13 @@ describe("persistCodexContextCompactionActivity", () => {
         messageId: "activity-message",
       });
     const params = {
-      run: {
-        runId: "run-1",
-        workspaceDir: "/workspace",
-        sessionTarget: {
-          agentId: "main",
-          sessionId: "session-1",
-          sessionKey: "agent:main:dashboard:session-1",
-          storePath: "/state/openclaw-agent.sqlite",
-        },
+      runId: "run-1",
+      cwd: "/workspace",
+      sessionTarget: {
+        agentId: "main",
+        sessionId: "session-1",
+        sessionKey: "agent:main:dashboard:session-1",
+        storePath: "/state/openclaw-agent.sqlite",
       },
       threadId: "thread-1",
       turnId: "turn-1",
diff --git a/extensions/codex/src/app-server/context-compaction-activity.ts b/extensions/codex/src/app-server/context-compaction-activity.ts
index 8ce22be5a6ec..7b55635809d6 100644
--- a/extensions/codex/src/app-server/context-compaction-activity.ts
+++ b/extensions/codex/src/app-server/context-compaction-activity.ts
@@ -11,13 +11,16 @@ import {
 const CONTEXT_COMPACTION_CUSTOM_TYPE = "openclaw.context-compaction";
 
 export async function persistCodexContextCompactionActivity(params: {
-  run: EmbeddedRunAttemptParams;
+  sessionTarget?: EmbeddedRunAttemptParams["sessionTarget"];
+  config?: EmbeddedRunAttemptParams["config"];
+  cwd?: string;
+  runId?: string;
   threadId: string;
   turnId: string;
   itemId: string;
   timestamp: number;
 }): Promise<void> {
-  const target = params.run.sessionTarget;
+  const target = params.sessionTarget;
   if (!target?.sessionId || !target.sessionKey || !target.storePath) {
     return;
   }
@@ -34,7 +37,7 @@ export async function persistCodexContextCompactionActivity(params: {
       threadId: params.threadId,
       turnId: params.turnId,
       itemId: params.itemId,
-      runId: params.run.runId,
+      ...(params.runId ? { runId: params.runId } : {}),
     },
     timestamp: params.timestamp,
     idempotencyKey: activityId,
@@ -45,8 +48,8 @@ export async function persistCodexContextCompactionActivity(params: {
       sessionId: target.sessionId,
       sessionKey: target.sessionKey,
       storePath: target.storePath,
-      config: params.run.config,
-      cwd: params.run.workspaceDir,
+      config: params.config,
+      cwd: params.cwd,
       eventId: activityId,
       message,
     });
@@ -61,7 +64,7 @@ export async function persistCodexContextCompactionActivity(params: {
       update: {
         message: appended.message,
         messageId: appended.messageId,
-        runId: params.run.runId,
+        ...(params.runId ? { runId: params.runId } : {}),
       },
     });
   } catch (error) {
diff --git a/extensions/codex/src/app-server/event-projector.ts b/extensions/codex/src/app-server/event-projector.ts
index 6fab913ef4b7..d1a81bd14571 100644
--- a/extensions/codex/src/app-server/event-projector.ts
+++ b/extensions/codex/src/app-server/event-projector.ts
@@ -522,7 +522,10 @@ export class CodexAppServerEventProjector {
         },
       });
       await persistCodexContextCompactionActivity({
-        run: this.params,
+        sessionTarget: this.params.sessionTarget,
+        config: this.params.config,
+        cwd: this.params.workspaceDir,
+        runId: this.params.runId,
         threadId: this.threadId,
         turnId: this.turnId,
         itemId,

From 0095168ae624810385869370979ffa467739b28c Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 08:38:57 -0700
Subject: [PATCH 015/124] fix(cli): render Nodes validation failures (#127223)

---
 src/cli/nodes-cli.coverage.test.ts      | 66 +++++++++++++++++
 src/cli/nodes-cli/register.invoke.ts    |  7 +-
 src/cli/nodes-cli/register.pairing.ts   |  6 +-
 src/cli/nodes-cli/register.status.ts    | 20 ++----
 src/cli/program.nodes-basic.e2e.test.ts | 57 +++++++++++++++
 test/cli-json-stdout.e2e.test.ts        | 95 +++++++++++++++++++++++++
 6 files changed, 226 insertions(+), 25 deletions(-)

diff --git a/src/cli/nodes-cli.coverage.test.ts b/src/cli/nodes-cli.coverage.test.ts
index 04572edf487b..a8f5ce050f52 100644
--- a/src/cli/nodes-cli.coverage.test.ts
+++ b/src/cli/nodes-cli.coverage.test.ts
@@ -249,6 +249,72 @@ describe("nodes-cli coverage", () => {
     expect(callGateway.mock.calls.map(([call]) => call.method)).toEqual(["node.pair.reject"]);
   });
 
+  it.each([
+    {
+      label: "status with an invalid last-connected duration",
+      command: "status",
+      args: ["nodes", "status", "--last-connected", "not-a-duration"],
+      message: "Invalid --last-connected: Invalid duration",
+    },
+    {
+      label: "list with an invalid last-connected duration",
+      command: "list",
+      args: ["nodes", "list", "--last-connected", "not-a-duration"],
+      message: "Invalid --last-connected: Invalid duration",
+    },
+    {
+      label: "status with an empty last-connected duration",
+      command: "status",
+      args: ["nodes", "status", "--last-connected", ""],
+      message: "Invalid --last-connected",
+    },
+    {
+      label: "list with a blank last-connected duration",
+      command: "list",
+      args: ["nodes", "list", "--last-connected", "   "],
+      message: "Invalid --last-connected",
+    },
+    {
+      label: "invoke with a blank node",
+      command: "invoke",
+      args: ["nodes", "invoke", "--node", "   ", "--command", "canvas.eval"],
+      message: "--node and --command required",
+    },
+    {
+      label: "invoke with a blank command",
+      command: "invoke",
+      args: ["nodes", "invoke", "--node", "mac-1", "--command", "   "],
+      message: "--node and --command required",
+    },
+    {
+      label: "rename with a blank name",
+      command: "rename",
+      args: ["nodes", "rename", "--node", "mac-1", "--name", "   "],
+      message: "--name must not be empty",
+    },
+  ])("reports $label once before calling the gateway", async ({ command, args, message }) => {
+    await expect(sharedProgram.parseAsync(args, { from: "user" })).rejects.toThrow("__exit__:1");
+
+    expect(callGateway).not.toHaveBeenCalled();
+    expect(runtimeErrors).toEqual([expect.stringContaining(`nodes ${command} failed: ${message}`)]);
+    expect(defaultRuntime.exit).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    ["invoke node", ["nodes", "invoke", "--command", "canvas.eval"]],
+    ["invoke command", ["nodes", "invoke", "--node", "mac-1"]],
+    ["rename name", ["nodes", "rename", "--node", "mac-1"]],
+  ])("preserves Commander validation for a missing %s", async (_label, args) => {
+    await withSuppressedStderr(async () => {
+      await expect(sharedProgram.parseAsync(args, { from: "user" })).rejects.toMatchObject({
+        code: "commander.missingMandatoryOptionValue",
+      });
+    });
+
+    expect(callGateway).not.toHaveBeenCalled();
+    expect(defaultRuntime.exit).not.toHaveBeenCalled();
+  });
+
   it("blocks system.run on nodes invoke", async () => {
     await expect(
       sharedProgram.parseAsync(["nodes", "invoke", "--node", "mac-1", "--command", "system.run"], {
diff --git a/src/cli/nodes-cli/register.invoke.ts b/src/cli/nodes-cli/register.invoke.ts
index 0eddf77aec90..834244fa5493 100644
--- a/src/cli/nodes-cli/register.invoke.ts
+++ b/src/cli/nodes-cli/register.invoke.ts
@@ -6,7 +6,7 @@ import {
 import type { Command } from "commander";
 import { randomIdempotencyKey } from "../../gateway/call.js";
 import { defaultRuntime } from "../../runtime.js";
-import { getNodesTheme, runNodesCommand } from "./cli-utils.js";
+import { runNodesCommand } from "./cli-utils.js";
 import {
   callNodesGatewayCli,
   nodesCallOpts,
@@ -41,10 +41,7 @@ export function registerNodesInvokeCommands(nodes: Command) {
           const nodeQuery = normalizeOptionalString(opts.node) ?? "";
           const command = normalizeOptionalString(opts.command) ?? "";
           if (!nodeQuery || !command) {
-            const { error } = getNodesTheme();
-            defaultRuntime.error(error("--node and --command required"));
-            defaultRuntime.exit(1);
-            return;
+            throw new Error("--node and --command required");
           }
           if (BLOCKED_NODE_INVOKE_COMMANDS.has(normalizeLowercaseStringOrEmpty(command))) {
             throw new Error(
diff --git a/src/cli/nodes-cli/register.pairing.ts b/src/cli/nodes-cli/register.pairing.ts
index aaea23ff46f4..ac5111ba86a8 100644
--- a/src/cli/nodes-cli/register.pairing.ts
+++ b/src/cli/nodes-cli/register.pairing.ts
@@ -230,15 +230,13 @@ export function registerNodesPairingCommands(nodes: Command) {
       .requiredOption("--name <displayName>", "New display name")
       .action(async (opts: NodesRpcOpts) => {
         await runNodesCommand("rename", async () => {
-          const nodeId = await resolveCliNodeId(opts, normalizeOptionalString(opts.node) ?? "");
           const name = normalizeOptionalString(opts.name) ?? "";
           if (!name) {
-            defaultRuntime.error(
+            throw new Error(
               `--name must not be empty. Run ${formatCliCommand("openclaw nodes list")} to see paired nodes, then rerun with --name <displayName>.`,
             );
-            defaultRuntime.exit(1);
-            return;
           }
+          const nodeId = await resolveCliNodeId(opts, normalizeOptionalString(opts.node) ?? "");
           const result = await callNodesGatewayCli("node.rename", opts, {
             nodeId,
             displayName: name,
diff --git a/src/cli/nodes-cli/register.status.ts b/src/cli/nodes-cli/register.status.ts
index 00656fce3502..1f18927f0cb6 100644
--- a/src/cli/nodes-cli/register.status.ts
+++ b/src/cli/nodes-cli/register.status.ts
@@ -160,26 +160,14 @@ function formatPendingApprovalCommand(raw: unknown, opts: NodesRpcOpts): string
   return formatCliCommand(args.map(quoteCliArg).join(" "));
 }
 
-function parseSinceMs(raw: unknown, label: string): number | undefined {
-  if (raw === undefined || raw === null) {
-    return undefined;
-  }
-  const value = normalizeOptionalString(raw) ?? (typeof raw === "number" ? String(raw) : null);
-  if (value === null) {
-    defaultRuntime.error(`${label}: invalid duration value`);
-    defaultRuntime.exit(1);
-    return undefined;
-  }
-  if (!value) {
+function parseSinceMs(raw: string | undefined, label: string): number | undefined {
+  if (raw === undefined) {
     return undefined;
   }
   try {
-    return parseDurationMs(value);
+    return parseDurationMs(raw);
   } catch (err) {
-    const message = formatErrorMessage(err);
-    defaultRuntime.error(`${label}: ${message}`);
-    defaultRuntime.exit(1);
-    return undefined;
+    throw new Error(`${label}: ${formatErrorMessage(err)}`, { cause: err });
   }
 }
 
diff --git a/src/cli/program.nodes-basic.e2e.test.ts b/src/cli/program.nodes-basic.e2e.test.ts
index 6fffc3d41b8b..677ee4979eb5 100644
--- a/src/cli/program.nodes-basic.e2e.test.ts
+++ b/src/cli/program.nodes-basic.e2e.test.ts
@@ -384,6 +384,37 @@ describe("cli program (nodes basics)", () => {
     expect(output).not.toContain("Two");
   });
 
+  it.each([
+    { command: "status", duration: "24h" },
+    { command: "status", duration: "1h30m" },
+    { command: "status", duration: "0" },
+    { command: "status", duration: " 24H " },
+    { command: "list", duration: "24h" },
+    { command: "list", duration: "1h30m" },
+    { command: "list", duration: "0" },
+    { command: "list", duration: " 24H " },
+  ])("preserves nodes $command --last-connected $duration", async ({ command, duration }) => {
+    const node = {
+      nodeId: "recent-node",
+      displayName: "Recent Node",
+      paired: true,
+      connected: true,
+      lastConnectedAtMs: Date.now() + 60_000,
+    };
+    programGatewayCallMock.mockImplementation(async (...args: unknown[]) => {
+      const { method } = (args[0] ?? {}) as { method?: string };
+      return method === "node.pair.list" ? { pending: [], paired: [node] } : { nodes: [node] };
+    });
+
+    await runProgram(["nodes", command, "--last-connected", duration, "--json"]);
+
+    const result = writeJsonArgAt(0) as {
+      nodes?: Array<{ nodeId: string }>;
+      paired?: Array<{ nodeId: string }>;
+    };
+    expect((result.nodes ?? result.paired)?.map(({ nodeId }) => nodeId)).toEqual(["recent-node"]);
+  });
+
   it.each([
     {
       label: "paired node details",
@@ -848,6 +879,32 @@ describe("cli program (nodes basics)", () => {
     expectGatewayRequest("node.pair.remove", { nodeId: "ios-node" });
   });
 
+  it("runs nodes rename and preserves the successful node.rename payload", async () => {
+    programGatewayCallMock.mockImplementation(async (...args: unknown[]) => {
+      const { method } = (args[0] ?? {}) as { method?: string };
+      return method === "node.list"
+        ? { nodes: [{ nodeId: "ios-node", displayName: "iOS Node", paired: true }] }
+        : { ok: true, nodeId: "ios-node", displayName: "Renamed Node" };
+    });
+
+    await runProgram([
+      "nodes",
+      "rename",
+      "--node",
+      "iOS Node",
+      "--name",
+      " Renamed Node ",
+      "--json",
+    ]);
+
+    expectGatewayRequest("node.rename", { nodeId: "ios-node", displayName: "Renamed Node" });
+    expect(writeJsonArgAt(0)).toEqual({
+      ok: true,
+      nodeId: "ios-node",
+      displayName: "Renamed Node",
+    });
+  });
+
   it("runs nodes invoke and calls node.invoke", async () => {
     mockGatewayWithIosNodeListAnd("node.invoke", {
       ok: true,
diff --git a/test/cli-json-stdout.e2e.test.ts b/test/cli-json-stdout.e2e.test.ts
index 9459e2544813..504721adac6c 100644
--- a/test/cli-json-stdout.e2e.test.ts
+++ b/test/cli-json-stdout.e2e.test.ts
@@ -379,6 +379,101 @@ describe("cli json stdout contract", () => {
     );
   });
 
+  it.each([
+    {
+      name: "status with an invalid duration in human mode",
+      args: ["nodes", "status", "--last-connected", "not-a-duration"],
+      message: "Invalid --last-connected: Invalid duration",
+      human: true,
+    },
+    {
+      name: "status with JSON before its invalid duration",
+      args: ["nodes", "status", "--json", "--last-connected", "not-a-duration"],
+      message: "Invalid --last-connected: Invalid duration",
+    },
+    {
+      name: "status with JSON after its invalid duration",
+      args: ["nodes", "status", "--last-connected", "not-a-duration", "--json"],
+      message: "Invalid --last-connected: Invalid duration",
+    },
+    {
+      name: "list with an invalid duration in human mode",
+      args: ["nodes", "list", "--last-connected", "not-a-duration"],
+      message: "Invalid --last-connected: Invalid duration",
+      human: true,
+    },
+    {
+      name: "list with JSON before its invalid duration",
+      args: ["nodes", "list", "--json", "--last-connected", "not-a-duration"],
+      message: "Invalid --last-connected: Invalid duration",
+    },
+    {
+      name: "list with JSON after its invalid duration",
+      args: ["nodes", "list", "--last-connected", "not-a-duration", "--json"],
+      message: "Invalid --last-connected: Invalid duration",
+    },
+    {
+      name: "invoke with an explicitly JSON blank node",
+      args: ["nodes", "invoke", "--node", "   ", "--command", "canvas.eval", "--json"],
+      message: "--node and --command required",
+    },
+    {
+      name: "invoke with an implicitly JSON blank node",
+      args: ["nodes", "invoke", "--node", "   ", "--command", "canvas.eval"],
+      message: "--node and --command required",
+    },
+    {
+      name: "invoke with an explicitly JSON blank command",
+      args: ["nodes", "invoke", "--node", "mac-1", "--command", "   ", "--json"],
+      message: "--node and --command required",
+    },
+    {
+      name: "invoke with an implicitly JSON blank command",
+      args: ["nodes", "invoke", "--node", "mac-1", "--command", "   "],
+      message: "--node and --command required",
+    },
+    {
+      name: "rename with a blank name",
+      args: ["nodes", "rename", "--node", "mac-1", "--name", "   ", "--json"],
+      message: "--name must not be empty",
+    },
+  ])("renders nodes $name through the shared validation owner", async (testCase) => {
+    await withTempHome(
+      async (tempHome) => {
+        const denyNetwork = Buffer.from(
+          `import net from "node:net";
+           net.Socket.prototype.connect = function () { throw new Error("AUTOQA_NETWORK_FORBIDDEN"); };
+           globalThis.fetch = async () => { throw new Error("AUTOQA_NETWORK_FORBIDDEN"); };`,
+        ).toString("base64");
+        const result = runBuiltCli(tempHome, testCase.args, {
+          NODE_OPTIONS: `--permission --allow-fs-read=* --import=data:text/javascript;base64,${denyNetwork}`,
+          NODE_DISABLE_COMPILE_CACHE: "1",
+          OPENCLAW_NO_RESPAWN: "1",
+          OPENCLAW_LOG_LEVEL: "silent",
+          OPENCLAW_STATE_DIR: path.join(tempHome, "isolated-state"),
+          OPENCLAW_CONFIG_PATH: path.join(tempHome, "missing-openclaw.json"),
+        });
+
+        expect(result.status, result.stderr).toBe(1);
+        if ("human" in testCase && testCase.human) {
+          expect(result.stdout).toBe("");
+          expect(result.stderr).toContain(`nodes ${testCase.args[1]} failed:`);
+        } else {
+          expect(JSON.parse(result.stdout)).toEqual({
+            ok: false,
+            error: {
+              type: "cli_error",
+              message: expect.stringContaining(testCase.message),
+            },
+          });
+        }
+        expect(result.stderr).toContain(testCase.message);
+        expect(result.stderr).not.toContain("AUTOQA_NETWORK_FORBIDDEN");
+      },
+      { prefix: "openclaw-nodes-json-failure-e2e-" },
+    );
+  });
+
   it.each([
     {
       name: "search with a leaf JSON flag",

From 5eb28a3b404c24006f94a811d4666d46af5e3b28 Mon Sep 17 00:00:00 2001
From: Yuval Dinodia <102706514+yetval@users.noreply.github.com>
Date: Fri, 21 Aug 2026 11:41:42 -0400
Subject: [PATCH 016/124] fix(outbound): retry queued deliveries when a channel
 adapter is unavailable (#126800)

* fix(outbound): retry queued deliveries when a channel adapter is unavailable

Delivery queue recovery classified "Outbound not configured for channel" as a
permanent provider rejection, so a queued message and its spooled attachment
were dead-lettered on the first attempt whenever the channel adapter was
momentarily unresolvable. That string is a local adapter-resolution failure
thrown by createChannelHandler, not a provider verdict, and the live send path
already treats it as retryable.

Remove the pattern so adapter unavailability consumes the normal retry budget.

* fix(outbound): type adapter lookup failures

---------

Co-authored-by: Altay <altay@hey.com>
---
 src/infra/outbound/deliver-channel.ts         |  5 ++-
 ...deliver.queue-adapter-availability.test.ts | 45 ++++++++++++++++++-
 src/infra/outbound/delivery-queue-recovery.ts |  1 -
 3 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/src/infra/outbound/deliver-channel.ts b/src/infra/outbound/deliver-channel.ts
index 0ca0b6449f8b..fba7a7388c6f 100644
--- a/src/infra/outbound/deliver-channel.ts
+++ b/src/infra/outbound/deliver-channel.ts
@@ -27,7 +27,7 @@ import type {
   DurableFinalDeliveryRequirements,
   OutboundDurableDeliverySupport,
 } from "./deliver-contracts.js";
-import type { OutboundDeliveryResult } from "./deliver-types.js";
+import { PlatformMessageNotDispatchedError, type OutboundDeliveryResult } from "./deliver-types.js";
 import {
   attachOutboundDeliveryCommitHook,
   type OutboundDeliveryCommitHook,
@@ -57,7 +57,8 @@ export async function createChannelHandler(params: ChannelHandlerParams): Promis
     return createPluginHandler({ ...params, outbound, message });
   });
   if (!handler) {
-    throw new Error(`Outbound not configured for channel: ${params.channel}`);
+    const message = `Outbound not configured for channel: ${params.channel}`;
+    throw new PlatformMessageNotDispatchedError(message, { cause: new Error(message) });
   }
   return scopeChannelHandler(handler, pluginRegistry);
 }
diff --git a/src/infra/outbound/deliver.queue-adapter-availability.test.ts b/src/infra/outbound/deliver.queue-adapter-availability.test.ts
index 0fb905a2689a..2b0b489e7b27 100644
--- a/src/infra/outbound/deliver.queue-adapter-availability.test.ts
+++ b/src/infra/outbound/deliver.queue-adapter-availability.test.ts
@@ -8,13 +8,14 @@ import { resetPluginRuntimeStateForTest, setActivePluginRegistry } from "../../p
 import { withPluginRuntimeRegistryScope } from "../../plugins/runtime/gateway-request-scope.js";
 import { createOutboundTestPlugin, createTestRegistry } from "../../test-utils/channel-plugins.js";
 import { getDeliveryQueueEntryStatus } from "../delivery-queue-sqlite.js";
+import { PlatformMessageNotDispatchedError } from "./deliver-types.js";
 import {
   boundedCronCompletionRetention,
   matrixOutboundForQueueTest,
 } from "./deliver.queue-integration.test-support.js";
 import { OUTBOUND_DELIVERY_QUEUE_NAME } from "./delivery-queue-media-staging.js";
 import { recoverPendingDeliveries, type DeliverFn } from "./delivery-queue-recovery.js";
-import { loadPendingDeliveries } from "./delivery-queue-storage.js";
+import { enqueueDelivery, loadPendingDeliveries } from "./delivery-queue-storage.js";
 import {
   createRecoveryLog,
   installDeliveryQueueTmpDirHooks,
@@ -132,6 +133,48 @@ describe("queued lazy outbound adapter availability", () => {
     ).toBe("completed");
   });
 
+  it("retains recovery custody when no outbound adapter can be resolved", async () => {
+    process.env.OPENCLAW_STATE_DIR = tmpDir;
+    setActivePluginRegistry(createEmptyPluginRegistry());
+    const id = await enqueueDelivery(
+      {
+        channel: "missing-adapter-test",
+        to: "recipient",
+        payloads: [{ text: "retry after adapter resolution" }],
+      },
+      tmpDir,
+    );
+    let deliveryError: unknown;
+    const recoveryDeliver = vi.fn<DeliverFn>(async (params) => {
+      try {
+        return await deliverOutboundPayloads(params);
+      } catch (error) {
+        deliveryError = error;
+        throw error;
+      }
+    });
+
+    const result = await recoverPendingDeliveries({
+      cfg: {} as OpenClawConfig,
+      deliver: recoveryDeliver,
+      log: createRecoveryLog(),
+      stateDir: tmpDir,
+    });
+
+    expect(result).toMatchObject({ failed: 1, recovered: 0, skippedMaxRetries: 0 });
+    expect(recoveryDeliver).toHaveBeenCalledOnce();
+    expect(deliveryError).toBeInstanceOf(PlatformMessageNotDispatchedError);
+    const pendingEntry = expectDefined(
+      (await loadPendingDeliveries(tmpDir))[0],
+      "retained adapter-miss delivery",
+    );
+    expect(pendingEntry).toMatchObject({ id, retryCount: 1 });
+    expect(pendingEntry.recoveryState).toBeUndefined();
+    expect(pendingEntry.platformSendAttemptId).toBeUndefined();
+    expect(pendingEntry.platformSendStartedAt).toBeUndefined();
+    expect(getDeliveryQueueEntryStatus(OUTBOUND_DELIVERY_QUEUE_NAME, id, tmpDir)).toBe("pending");
+  });
+
   it("does not replay a provider call that already crossed the ambiguous send boundary", async () => {
     process.env.OPENCLAW_STATE_DIR = tmpDir;
     setActivePluginRegistry(
diff --git a/src/infra/outbound/delivery-queue-recovery.ts b/src/infra/outbound/delivery-queue-recovery.ts
index ccbe174e18fc..928dbdcb2b1c 100644
--- a/src/infra/outbound/delivery-queue-recovery.ts
+++ b/src/infra/outbound/delivery-queue-recovery.ts
@@ -94,7 +94,6 @@ const PERMANENT_ERROR_PATTERNS: readonly RegExp[] = [
   /forbidden: bot was kicked/i,
   /chat_id is empty/i,
   /recipient is not a valid/i,
-  /outbound not configured for channel/i,
   /ambiguous .* recipient/i,
   /User .* not in room/i,
 ];

From 9c64ed87e90d686677d6a9cfbef421457a4f268a Mon Sep 17 00:00:00 2001
From: Dallin Romney <dallinromney@gmail.com>
Date: Fri, 21 Aug 2026 08:50:34 -0700
Subject: [PATCH 017/124] test(agents): keep fallback E2E runtime coherent
 (#127079)

---
 src/agents/model-fallback.run-embedded.e2e.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/agents/model-fallback.run-embedded.e2e.test.ts b/src/agents/model-fallback.run-embedded.e2e.test.ts
index 394b62b10a7d..6396b6d41b1f 100644
--- a/src/agents/model-fallback.run-embedded.e2e.test.ts
+++ b/src/agents/model-fallback.run-embedded.e2e.test.ts
@@ -46,6 +46,7 @@ const installRunEmbeddedMocks = () => {
   // exercises fallback orchestration without live model/provider calls.
   vi.doMock("../plugins/runtime.js", () => ({
     getActivePluginRegistry: () => null,
+    getActivePluginRegistryWorkspaceDir: () => undefined,
     requireActivePluginRegistry: () => ({}),
   }));
   vi.doMock("./harness/runtime-plugin.js", () => ({
@@ -79,7 +80,6 @@ let runWithModelFallback: typeof import("./model-fallback-runner.js").runWithMod
 let runEmbeddedAgentEntry: typeof import("./embedded-agent-runner/run-entry.js").runEmbeddedAgentEntry;
 
 beforeAll(async () => {
-  vi.resetModules();
   installRunEmbeddedMocks();
   runEmbeddedAgent = wrapRunWithTestAdmission(
     (await import("./embedded-agent-runner/run.js")).runEmbeddedAgent,

From 870f936851f9f7191586115a5a0132c2f4752d44 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 08:52:12 -0700
Subject: [PATCH 018/124] perf(sessions): avoid full key tokenization (#127249)

Amp-Thread-ID: https://ampcode.com/threads/T-01a02481-e149-77dd-a132-a2797e238ef8

Co-authored-by: Amp <amp@ampcode.com>
---
 src/sessions/session-key-utils.ts | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/sessions/session-key-utils.ts b/src/sessions/session-key-utils.ts
index 70600a8a1fb8..f09c3ab760e6 100644
--- a/src/sessions/session-key-utils.ts
+++ b/src/sessions/session-key-utils.ts
@@ -263,16 +263,16 @@ export function parseAgentSessionKey(
   if (!raw) {
     return null;
   }
-  const parts = raw.split(":");
-  if (parts.length < 3 || !parts[1] || !parts[2]) {
+  if (!raw.startsWith("agent:")) {
     return null;
   }
-  if (parts[0] !== "agent") {
+  const agentIdEnd = raw.indexOf(":", "agent:".length);
+  if (agentIdEnd === -1) {
     return null;
   }
-  const agentId = normalizeOptionalString(parts[1]);
-  const rest = parts.slice(2).join(":");
-  if (!agentId || !rest) {
+  const agentId = normalizeOptionalString(raw.slice("agent:".length, agentIdEnd));
+  const rest = raw.slice(agentIdEnd + 1);
+  if (!agentId || !rest || rest.startsWith(":")) {
     return null;
   }
   return { agentId, rest };

From 407930cb6ac50d86bd349f8501c368df2470a294 Mon Sep 17 00:00:00 2001
From: WhatsSkiLL <whatsskilll@gmail.com>
Date: Fri, 21 Aug 2026 17:54:47 +0200
Subject: [PATCH 019/124] feat(wear): add direct agent, session, and model
 pickers (#126863)

* feat(wear): add searchable context pickers

* fix(wear): simplify context picker rows

* fix(wear): prioritize chat actions over context

* fix(wear): keep chat follow above context controls

* fix(wear): keep context labels localized

* fix(wear): refine context picker layout and close

* fix(wear): sync picker locale resources

* fix(wear): negotiate picker search support

---------

Co-authored-by: IWhatsskill <284122573+IWhatsskill@users.noreply.github.com>
---
 apps/.i18n/native-source.json                 | 108 +++-
 apps/android/app/lint.xml                     |   8 +
 .../openclaw/app/wear/WearProxyController.kt  |  33 +-
 .../app/wear/WearProxyControllerTest.kt       |  63 +-
 .../ai/openclaw/wear/shared/WearProtocol.kt   |   2 +
 .../openclaw/wear/shared/WearProtocolTest.kt  |   2 +
 .../java/ai/openclaw/wear/MainActivity.kt     |  50 +-
 .../ai/openclaw/wear/WearCompanionUiModels.kt |  37 ++
 .../ai/openclaw/wear/WearGatewayRepository.kt |  17 +-
 .../main/java/ai/openclaw/wear/WearScreens.kt | 560 +++++++++++++-----
 .../java/ai/openclaw/wear/WearViewModel.kt    | 143 ++++-
 .../wear/src/main/res/values/strings.xml      |  13 +-
 .../java/ai/openclaw/wear/MainActivityTest.kt |  80 ++-
 .../wear/WearGatewayRepositoryTest.kt         |  64 +-
 14 files changed, 964 insertions(+), 216 deletions(-)

diff --git a/apps/.i18n/native-source.json b/apps/.i18n/native-source.json
index 23810ce0d2aa..d0790a611b60 100644
--- a/apps/.i18n/native-source.json
+++ b/apps/.i18n/native-source.json
@@ -961,6 +961,17 @@
         }
       ]
     },
+    {
+      "id": "native.android.adedee12882a5e48",
+      "source": "%1$s: %2$s",
+      "surface": "android",
+      "sites": [
+        {
+          "kind": "resource-string",
+          "path": "apps/android/wear/src/main/res/values/strings.xml"
+        }
+      ]
+    },
     {
       "id": "native.android.5b1f512f56214522",
       "source": "+${diff.added}",
@@ -1433,6 +1444,17 @@
         }
       ]
     },
+    {
+      "id": "native.android.4e2d71e58e9b5d58",
+      "source": "Active on phone",
+      "surface": "android",
+      "sites": [
+        {
+          "kind": "resource-string",
+          "path": "apps/android/wear/src/main/res/values/strings.xml"
+        }
+      ]
+    },
     {
       "id": "native.android.ccd226a2c0e85242",
       "source": "Active task list is at its limit",
@@ -3558,6 +3580,10 @@
         {
           "kind": "ui-call",
           "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/chat/ChatScreen.kt"
+        },
+        {
+          "kind": "resource-string",
+          "path": "apps/android/wear/src/main/res/values/strings.xml"
         }
       ]
     },
@@ -6479,6 +6505,28 @@
         }
       ]
     },
+    {
+      "id": "native.android.df6908aa0d65572b",
+      "source": "Find a model",
+      "surface": "android",
+      "sites": [
+        {
+          "kind": "resource-string",
+          "path": "apps/android/wear/src/main/res/values/strings.xml"
+        }
+      ]
+    },
+    {
+      "id": "native.android.98780014fd21c179",
+      "source": "Find a session",
+      "surface": "android",
+      "sites": [
+        {
+          "kind": "resource-string",
+          "path": "apps/android/wear/src/main/res/values/strings.xml"
+        }
+      ]
+    },
     {
       "id": "native.android.e889efed8c081333",
       "source": "Find on ClawHub",
@@ -8338,6 +8386,10 @@
         {
           "kind": "ui-call",
           "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/WorkspaceFilesScreen.kt"
+        },
+        {
+          "kind": "resource-string",
+          "path": "apps/android/wear/src/main/res/values/strings.xml"
         }
       ]
     },
@@ -9344,17 +9396,6 @@
         }
       ]
     },
-    {
-      "id": "native.android.2e7778c3617afdb8",
-      "source": "Next %1$s",
-      "surface": "android",
-      "sites": [
-        {
-          "kind": "resource-string",
-          "path": "apps/android/wear/src/main/res/values/strings.xml"
-        }
-      ]
-    },
     {
       "id": "native.android.56de778dd64c4cba",
       "source": "Next Cycle",
@@ -9697,6 +9738,10 @@
         {
           "kind": "ui-call",
           "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/chat/ChatDictation.kt"
+        },
+        {
+          "kind": "resource-string",
+          "path": "apps/android/wear/src/main/res/values/strings.xml"
         }
       ]
     },
@@ -10925,6 +10970,17 @@
         }
       ]
     },
+    {
+      "id": "native.android.86743582a5bdbdca",
+      "source": "Open on watch",
+      "surface": "android",
+      "sites": [
+        {
+          "kind": "resource-string",
+          "path": "apps/android/wear/src/main/res/values/strings.xml"
+        }
+      ]
+    },
     {
       "id": "native.android.bd4741b9b157a8b9",
       "source": "Open profile",
@@ -12291,17 +12347,6 @@
         }
       ]
     },
-    {
-      "id": "native.android.ab710f2d490e510d",
-      "source": "Previous %1$s",
-      "surface": "android",
-      "sites": [
-        {
-          "kind": "resource-string",
-          "path": "apps/android/wear/src/main/res/values/strings.xml"
-        }
-      ]
-    },
     {
       "id": "native.android.f24b4fe4204360d9",
       "source": "Prioritizes connected Bluetooth microphones.",
@@ -14411,6 +14456,10 @@
         {
           "kind": "ui-named-argument",
           "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/design/ClawComponents.kt"
+        },
+        {
+          "kind": "resource-string",
+          "path": "apps/android/wear/src/main/res/values/strings.xml"
         }
       ]
     },
@@ -14469,6 +14518,17 @@
         }
       ]
     },
+    {
+      "id": "native.android.bcab8e57d5c3490d",
+      "source": "Search models",
+      "surface": "android",
+      "sites": [
+        {
+          "kind": "resource-string",
+          "path": "apps/android/wear/src/main/res/values/strings.xml"
+        }
+      ]
+    },
     {
       "id": "native.android.8263e0efaec65c14",
       "source": "Search proposals",
@@ -14499,6 +14559,10 @@
         {
           "kind": "ui-call",
           "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/SidebarComponents.kt"
+        },
+        {
+          "kind": "resource-string",
+          "path": "apps/android/wear/src/main/res/values/strings.xml"
         }
       ]
     },
diff --git a/apps/android/app/lint.xml b/apps/android/app/lint.xml
index e0fee5d8c7ca..be2c631b686f 100644
--- a/apps/android/app/lint.xml
+++ b/apps/android/app/lint.xml
@@ -8,6 +8,14 @@
     <!-- OpenClaw uses date-based version codes (yyyyMMddNN), which are high but still below the Android max. -->
     <issue id="HighAppVersionCode" severity="ignore" />
 
+    <!-- Native locale refresh removes translated rows after source strings are removed. -->
+    <issue id="ExtraTranslation">
+        <ignore regexp="previous_item|next_item" />
+    </issue>
+    <issue id="UnusedResources">
+        <ignore regexp="previous_item|next_item" />
+    </issue>
+
     <!-- Target SDK follows the current release train; bump only after platform compatibility testing. -->
     <issue id="OldTargetApi" severity="ignore" />
 </lint>
diff --git a/apps/android/app/src/main/java/ai/openclaw/app/wear/WearProxyController.kt b/apps/android/app/src/main/java/ai/openclaw/app/wear/WearProxyController.kt
index dfd44ef55648..57091fc7d95a 100644
--- a/apps/android/app/src/main/java/ai/openclaw/app/wear/WearProxyController.kt
+++ b/apps/android/app/src/main/java/ai/openclaw/app/wear/WearProxyController.kt
@@ -140,8 +140,14 @@ internal class WearProxyController(
         "capabilities",
         buildJsonArray {
           WearProxyCapability.entries
-            .filter { capability -> capability != WearProxyCapability.ModelControls || hasOperatorAdminScope() }
-            .forEach { capability -> add(JsonPrimitive(capability.wireValue)) }
+            .filter { capability ->
+              when (capability) {
+                WearProxyCapability.ModelControls,
+                WearProxyCapability.ModelCatalogSearch,
+                -> hasOperatorAdminScope()
+                else -> true
+              }
+            }.forEach { capability -> add(JsonPrimitive(capability.wireValue)) }
         },
       )
       activeAgentId()?.takeIf(String::isNotBlank)?.let { put("activeAgentId", it.takeCodePoints(MAX_AGENT_ID_CHARS)) }
@@ -200,16 +206,24 @@ internal class WearProxyController(
   }
 
   private fun listModels(params: JsonObject): JsonObject {
-    params.requireOnly("selectedModelRef")
+    params.requireOnly("selectedModelRef", "query")
+    val query = params.optionalStringParam("query", MAX_SEARCH_QUERY_CHARS)?.trim().orEmpty()
     val selected =
       canonicalModelRef(params.optionalStringParam("selectedModelRef", MAX_MODEL_REF_CHARS))
         ?: canonicalModelRef(selectedModelRef())
     val availableModels = availableModels()
-    // The Watch picker moves one adjacent model at a time and reloads after each choice.
+    val matchingModels =
+      availableModels.filter { (ref, model) ->
+        query.isBlank() || model.name.contains(query, ignoreCase = true) || ref.contains(query, ignoreCase = true)
+      }
+    // Queries match the full catalog before the bounded transport response.
+    // Blank requests keep the selected model centered in the compact Watch list.
     // Centering keeps both directions reachable without exceeding the message cap.
     val selectedIndex = availableModels.indexOfFirst { (ref) -> ref == selected }
     val boundedModels =
-      if (availableModels.size <= MAX_MODEL_COUNT || selectedIndex < 0) {
+      if (query.isNotBlank()) {
+        matchingModels.take(MAX_MODEL_COUNT)
+      } else if (availableModels.size <= MAX_MODEL_COUNT || selectedIndex < 0) {
         availableModels.take(MAX_MODEL_COUNT)
       } else {
         val start =
@@ -275,8 +289,10 @@ internal class WearProxyController(
   }
 
   private suspend fun listSessions(params: JsonObject): JsonObject {
-    params.requireOnly("limit", "selectedSessionKey")
+    params.requireOnly("limit", "offset", "search", "selectedSessionKey")
     val limit = params.intParam("limit", default = DEFAULT_SESSION_LIMIT, range = 1..MAX_SESSION_LIMIT)
+    val offset = params.optionalIntParam("offset", range = 0..MAX_SESSION_OFFSET)
+    val search = params.optionalStringParam("search", MAX_SEARCH_QUERY_CHARS)?.trim()?.takeIf(String::isNotEmpty)
     val selectedSessionKey = params.optionalStringParam("selectedSessionKey", MAX_SESSION_KEY_CHARS)
     val agentId = activeAgentId()?.trim()?.takeIf(String::isNotEmpty)
     val gatewayResult =
@@ -284,6 +300,8 @@ internal class WearProxyController(
         "sessions.list",
         buildJsonObject {
           put("limit", limit)
+          offset?.let { put("offset", it) }
+          search?.let { put("search", it) }
           put("includeGlobal", false)
           put("includeUnknown", false)
           agentId?.let { put("agentId", it.takeCodePoints(MAX_AGENT_ID_CHARS)) }
@@ -320,6 +338,7 @@ internal class WearProxyController(
       put("sessions", JsonArray(sessions))
       agentId?.let { put("activeAgentId", it.takeCodePoints(MAX_AGENT_ID_CHARS)) }
       if (selectedSessionKey != null) put("selectedSessionValid", selectedSessionValid)
+      gatewayResult["nextOffset"].longPrimitiveOrNull()?.let { put("nextOffset", it) }
       gatewayResult["hasMore"].booleanPrimitiveOrNull()?.let { put("hasMore", it) }
       gatewayResult["totalCount"].longPrimitiveOrNull()?.let { put("totalCount", it) }
     }
@@ -386,6 +405,8 @@ internal class WearProxyController(
   private companion object {
     const val DEFAULT_SESSION_LIMIT = 20
     const val MAX_SESSION_LIMIT = 50
+    const val MAX_SESSION_OFFSET = 100_000
+    const val MAX_SEARCH_QUERY_CHARS = 200
     const val DEFAULT_HISTORY_LIMIT = 20
     const val MAX_HISTORY_LIMIT = 20
     const val DEFAULT_HISTORY_CHARS = 2_000
diff --git a/apps/android/app/src/test/java/ai/openclaw/app/wear/WearProxyControllerTest.kt b/apps/android/app/src/test/java/ai/openclaw/app/wear/WearProxyControllerTest.kt
index 7d995ac604da..90501829f603 100644
--- a/apps/android/app/src/test/java/ai/openclaw/app/wear/WearProxyControllerTest.kt
+++ b/apps/android/app/src/test/java/ai/openclaw/app/wear/WearProxyControllerTest.kt
@@ -61,7 +61,7 @@ class WearProxyControllerTest {
     }
 
   @Test
-  fun statusAdvertisesModelControlsOnlyWithOperatorAdminScope() =
+  fun statusAdvertisesModelCapabilitiesOnlyWithOperatorAdminScope() =
     runTest {
       var hasOperatorAdminScope = false
       val controller =
@@ -88,8 +88,10 @@ class WearProxyControllerTest {
 
       assertEquals(
         WearProxyCapability.entries
-          .filter { it != WearProxyCapability.ModelControls }
-          .map(WearProxyCapability::wireValue),
+          .filter {
+            it != WearProxyCapability.ModelControls &&
+              it != WearProxyCapability.ModelCatalogSearch
+          }.map(WearProxyCapability::wireValue),
         limitedCapabilities,
       )
       assertEquals(
@@ -413,6 +415,43 @@ class WearProxyControllerTest {
       assertEquals("openai/gpt-59", refs.last())
     }
 
+  @Test
+  fun modelSearchFiltersTheFullCatalogBeforeApplyingTheTransportCap() =
+    runTest {
+      val controller =
+        WearProxyController(
+          requestGateway = { _, _ -> buildJsonObject {} },
+          isGatewayConnected = { true },
+          gatewayStatusText = { "Connected" },
+          models = {
+            (0 until 80).map { index ->
+              WearProxyModel(ref = "provider/model-$index", name = "Model $index")
+            }
+          },
+        )
+
+      val listed =
+        controller.handle(
+          request(
+            WearRpcMethod.ModelsList,
+            buildJsonObject { put("query", "model-79") },
+          ),
+        )
+      val refs =
+        checkNotNull(listed.result)
+          .jsonObject
+          .getValue("models")
+          .jsonArray
+          .map { model ->
+            model.jsonObject
+              .getValue("ref")
+              .jsonPrimitive
+              .content
+          }
+
+      assertEquals(listOf("provider/model-79"), refs)
+    }
+
   @Test
   fun modelListWindowKeepsAdjacentModelsReachableAcrossTheCap() =
     runTest {
@@ -613,7 +652,7 @@ class WearProxyControllerTest {
             requestedMethod = method
             requestedParams = params
             json.parseToJsonElement(
-              """{"sessions":[{"key":"agent:main","displayName":"Main","updatedAt":7,"modelProvider":"openai","model":"gpt-test","lastMessage":"hidden"}],"hasMore":true,"totalCount":9}""",
+              """{"sessions":[{"key":"agent:main","displayName":"Main","updatedAt":7,"modelProvider":"openai","model":"gpt-test","lastMessage":"hidden"}],"hasMore":true,"nextOffset":10,"totalCount":9}""",
             )
           },
           isGatewayConnected = { true },
@@ -625,14 +664,18 @@ class WearProxyControllerTest {
         controller.handle(
           request(
             WearRpcMethod.SessionsList,
-            buildJsonObject { put("limit", 5) },
+            buildJsonObject {
+              put("limit", 5)
+              put("offset", 5)
+              put("search", "older")
+            },
           ),
         )
 
       assertEquals("sessions.list", requestedMethod)
       assertEquals(
         json
-          .parseToJsonElement("""{"limit":5,"includeGlobal":false,"includeUnknown":false,"agentId":"main"}""")
+          .parseToJsonElement("""{"limit":5,"offset":5,"search":"older","includeGlobal":false,"includeUnknown":false,"agentId":"main"}""")
           .jsonObject,
         requestedParams,
       )
@@ -654,6 +697,14 @@ class WearProxyControllerTest {
           .content
           .toBoolean(),
       )
+      assertEquals(
+        10,
+        result
+          .getValue("nextOffset")
+          .jsonPrimitive
+          .content
+          .toInt(),
+      )
     }
 
   @Test
diff --git a/apps/android/wear-shared/src/main/java/ai/openclaw/wear/shared/WearProtocol.kt b/apps/android/wear-shared/src/main/java/ai/openclaw/wear/shared/WearProtocol.kt
index 24a2f2ac7f42..ff54943cb18b 100644
--- a/apps/android/wear-shared/src/main/java/ai/openclaw/wear/shared/WearProtocol.kt
+++ b/apps/android/wear-shared/src/main/java/ai/openclaw/wear/shared/WearProtocol.kt
@@ -74,7 +74,9 @@ enum class WearProxyCapability(
   AgentControls(wireValue = "agent-controls"),
   GatewayControls(wireValue = "gateway-controls"),
   ModelControls(wireValue = "model-controls"),
+  ModelCatalogSearch(wireValue = "model-catalog-search"),
   SessionSelectionLookup(wireValue = "session-selection-lookup"),
+  SessionSearchPagination(wireValue = "session-search-pagination"),
   AgentPulse(wireValue = "agent-pulse"),
   AttemptScopedRealtimeAudio(wireValue = "attempt-scoped-realtime-audio"),
   ;
diff --git a/apps/android/wear-shared/src/test/java/ai/openclaw/wear/shared/WearProtocolTest.kt b/apps/android/wear-shared/src/test/java/ai/openclaw/wear/shared/WearProtocolTest.kt
index 86242ca5d0c5..276b05e9958b 100644
--- a/apps/android/wear-shared/src/test/java/ai/openclaw/wear/shared/WearProtocolTest.kt
+++ b/apps/android/wear-shared/src/test/java/ai/openclaw/wear/shared/WearProtocolTest.kt
@@ -143,7 +143,9 @@ class WearProtocolTest {
     assertEquals("agent-controls", WearProxyCapability.AgentControls.wireValue)
     assertEquals("gateway-controls", WearProxyCapability.GatewayControls.wireValue)
     assertEquals("model-controls", WearProxyCapability.ModelControls.wireValue)
+    assertEquals("model-catalog-search", WearProxyCapability.ModelCatalogSearch.wireValue)
     assertEquals("session-selection-lookup", WearProxyCapability.SessionSelectionLookup.wireValue)
+    assertEquals("session-search-pagination", WearProxyCapability.SessionSearchPagination.wireValue)
     assertEquals("agent-pulse", WearProxyCapability.AgentPulse.wireValue)
     assertEquals(
       "attempt-scoped-realtime-audio",
diff --git a/apps/android/wear/src/main/java/ai/openclaw/wear/MainActivity.kt b/apps/android/wear/src/main/java/ai/openclaw/wear/MainActivity.kt
index a456a8f4ffde..650f1030d994 100644
--- a/apps/android/wear/src/main/java/ai/openclaw/wear/MainActivity.kt
+++ b/apps/android/wear/src/main/java/ai/openclaw/wear/MainActivity.kt
@@ -17,6 +17,7 @@ import androidx.activity.ComponentActivity
 import androidx.activity.compose.LocalActivity
 import androidx.activity.compose.rememberLauncherForActivityResult
 import androidx.activity.compose.setContent
+import androidx.activity.result.ActivityResultLauncher
 import androidx.activity.result.contract.ActivityResultContracts
 import androidx.activity.viewModels
 import androidx.compose.runtime.Composable
@@ -203,6 +204,9 @@ internal fun OpenClawWearApp(
   val messageLabel = stringResource(R.string.message)
   val messageTitle = stringResource(R.string.message_agent)
   val sendLabel = stringResource(R.string.send)
+  val sessionSearchTitle = stringResource(R.string.search_sessions_title)
+  val modelSearchTitle = stringResource(R.string.search_models_title)
+  val searchLabel = stringResource(R.string.search)
 
   fun submitMessage(rawMessage: String) {
     val message = rawMessage.trim()
@@ -254,6 +258,42 @@ internal fun OpenClawWearApp(
         interaction = WearInteractionState.READY
       }
     }
+  val sessionSearchLauncher =
+    rememberLauncherForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
+      val query =
+        result.data
+          ?.let(RemoteInput::getResultsFromIntent)
+          ?.getCharSequence(REMOTE_INPUT_KEY)
+          ?.toString()
+      if (result.resultCode == Activity.RESULT_OK && !query.isNullOrBlank()) {
+        viewModel.searchSessions(query)
+      }
+    }
+  val modelSearchLauncher =
+    rememberLauncherForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
+      val query =
+        result.data
+          ?.let(RemoteInput::getResultsFromIntent)
+          ?.getCharSequence(REMOTE_INPUT_KEY)
+          ?.toString()
+      if (result.resultCode == Activity.RESULT_OK && !query.isNullOrBlank()) {
+        viewModel.searchModels(query)
+      }
+    }
+
+  fun launchSearchInput(
+    title: String,
+    launcher: ActivityResultLauncher<Intent>,
+  ) {
+    val remoteInput = RemoteInput.Builder(REMOTE_INPUT_KEY).setLabel(searchLabel).build()
+    val intent =
+      RemoteInputIntentHelper.createActionRemoteInputIntent().also { inputIntent ->
+        RemoteInputIntentHelper.putRemoteInputsExtra(inputIntent, listOf(remoteInput))
+        RemoteInputIntentHelper.putTitleExtra(inputIntent, title)
+        RemoteInputIntentHelper.putConfirmLabelExtra(inputIntent, searchLabel)
+      }
+    launcher.launch(intent)
+  }
 
   fun startRealtimeTalk() {
     speaker.stop()
@@ -466,15 +506,23 @@ internal fun OpenClawWearApp(
           viewModel.selectAgent(agentId)
         },
         onSelectSession = { sessionKey ->
-          state.sessions.firstOrNull { it.key == sessionKey }?.let { session ->
+          (
+            state.sessionSearchResults.firstOrNull { it.key == sessionKey }
+              ?: state.sessions.firstOrNull { it.key == sessionKey }
+          )?.let { session ->
             leaveConversationContext()
             viewModel.openSession(session)
           }
         },
+        onSearchSessions = { launchSearchInput(sessionSearchTitle, sessionSearchLauncher) },
+        onLoadMoreSessionSearch = viewModel::loadMoreSessionSearch,
+        onClearSessionSearch = viewModel::clearSessionSearch,
         onSelectModel = { modelRef ->
           leaveConversationContext()
           viewModel.selectModel(modelRef)
         },
+        onSearchModels = { launchSearchInput(modelSearchTitle, modelSearchLauncher) },
+        onClearModelSearch = viewModel::clearModelSearch,
         onAgentPulseVisibilityChanged = viewModel::setAgentPulseVisible,
         onAgentPulseRefresh = viewModel::refreshAgentPulse,
         onRefresh = viewModel::refresh,
diff --git a/apps/android/wear/src/main/java/ai/openclaw/wear/WearCompanionUiModels.kt b/apps/android/wear/src/main/java/ai/openclaw/wear/WearCompanionUiModels.kt
index 0b3b745363f5..7d46e5dca37a 100644
--- a/apps/android/wear/src/main/java/ai/openclaw/wear/WearCompanionUiModels.kt
+++ b/apps/android/wear/src/main/java/ai/openclaw/wear/WearCompanionUiModels.kt
@@ -34,6 +34,8 @@ internal data class WearSessionSummary(
   val title: String?,
   val updatedAtEpochMillis: Long?,
   val selected: Boolean,
+  val activeOnPhone: Boolean = false,
+  val openOnWatch: Boolean = false,
 )
 
 internal data class WearModelSummary(
@@ -49,9 +51,17 @@ internal data class WearConversationSnapshot(
   val agentControlsSupported: Boolean = false,
   val gatewayControlsSupported: Boolean = false,
   val activeSessionId: String? = null,
+  val phoneActiveSessionId: String? = null,
   val sessions: List<WearSessionSummary> = emptyList(),
+  val sessionSearchQuery: String? = null,
+  val sessionSearchResults: List<WearSessionSummary> = emptyList(),
+  val sessionSearchHasMore: Boolean = false,
+  val sessionSearchSupported: Boolean = false,
   val models: List<WearModelSummary> = emptyList(),
+  val modelSearchQuery: String? = null,
+  val modelSearchResults: List<WearModelSummary> = emptyList(),
   val modelControlsSupported: Boolean = false,
+  val modelSearchSupported: Boolean = false,
   val messages: List<WearChatMessage> = emptyList(),
   val streamingAssistantText: String? = null,
   val pendingRunCount: Int = 0,
@@ -103,6 +113,7 @@ internal fun WearUiState.toConversationSnapshot(): WearConversationSnapshot? {
     agentControlsSupported = WearProxyCapability.AgentControls in proxyCapabilities,
     gatewayControlsSupported = WearProxyCapability.GatewayControls in proxyCapabilities,
     activeSessionId = selectedSession?.key,
+    phoneActiveSessionId = phoneActiveSessionKey,
     sessions =
       sessions.map { session ->
         WearSessionSummary(
@@ -110,8 +121,24 @@ internal fun WearUiState.toConversationSnapshot(): WearConversationSnapshot? {
           title = session.title,
           updatedAtEpochMillis = session.updatedAt,
           selected = session.key == selectedSession?.key,
+          activeOnPhone = session.key == phoneActiveSessionKey,
+          openOnWatch = session.key == selectedSession?.key,
         )
       },
+    sessionSearchQuery = sessionSearchQuery,
+    sessionSearchResults =
+      sessionSearchResults.map { session ->
+        WearSessionSummary(
+          id = session.key,
+          title = session.title,
+          updatedAtEpochMillis = session.updatedAt,
+          selected = session.key == selectedSession?.key,
+          activeOnPhone = session.key == phoneActiveSessionKey,
+          openOnWatch = session.key == selectedSession?.key,
+        )
+      },
+    sessionSearchHasMore = sessionSearchHasMore,
+    sessionSearchSupported = WearProxyCapability.SessionSearchPagination in proxyCapabilities,
     models =
       models.map { model ->
         WearModelSummary(
@@ -121,6 +148,16 @@ internal fun WearUiState.toConversationSnapshot(): WearConversationSnapshot? {
         )
       },
     modelControlsSupported = WearProxyCapability.ModelControls in proxyCapabilities,
+    modelSearchSupported = WearProxyCapability.ModelCatalogSearch in proxyCapabilities,
+    modelSearchQuery = modelSearchQuery,
+    modelSearchResults =
+      modelSearchResults.map { model ->
+        WearModelSummary(
+          ref = model.ref,
+          name = model.name,
+          selected = model.ref == selectedModelRef,
+        )
+      },
     messages = messages,
     streamingAssistantText = streamText,
     pendingRunCount = if (activeRunId != null) 1 else 0,
diff --git a/apps/android/wear/src/main/java/ai/openclaw/wear/WearGatewayRepository.kt b/apps/android/wear/src/main/java/ai/openclaw/wear/WearGatewayRepository.kt
index d128a908c4e5..eca56f8cabf4 100644
--- a/apps/android/wear/src/main/java/ai/openclaw/wear/WearGatewayRepository.kt
+++ b/apps/android/wear/src/main/java/ai/openclaw/wear/WearGatewayRepository.kt
@@ -117,6 +117,8 @@ internal data class WearSessionList(
   val eventStreamId: String? = null,
   val activeAgentId: String? = null,
   val selectedSessionValid: Boolean = false,
+  val hasMore: Boolean = false,
+  val nextOffset: Int? = null,
 )
 
 internal data class WearModel(
@@ -286,6 +288,7 @@ internal class WearGatewayRepository(
     expectedNodeId: String,
     capabilities: Set<WearProxyCapability>,
     selectedModelRef: String? = null,
+    query: String? = null,
   ): WearModelList {
     capabilities.require(WearProxyCapability.ModelControls)
     val response =
@@ -293,6 +296,9 @@ internal class WearGatewayRepository(
         WearRpcMethod.ModelsList,
         buildJsonObject {
           selectedModelRef?.let { put("selectedModelRef", it) }
+          if (WearProxyCapability.ModelCatalogSearch in capabilities) {
+            query?.takeIf(String::isNotBlank)?.let { put("query", it) }
+          }
         },
         expectedNodeId,
         requirePreferredNode = true,
@@ -370,13 +376,20 @@ internal class WearGatewayRepository(
     expectedNodeId: String? = null,
     selectedSessionKey: String? = null,
     capabilities: Set<WearProxyCapability> = emptySet(),
+    limit: Int = 30,
+    offset: Int? = null,
+    search: String? = null,
   ): WearSessionList {
     val response =
       requester
         .request(
           WearRpcMethod.SessionsList,
           buildJsonObject {
-            put("limit", 30)
+            put("limit", limit)
+            if (WearProxyCapability.SessionSearchPagination in capabilities) {
+              offset?.let { put("offset", it) }
+              search?.takeIf(String::isNotBlank)?.let { put("search", it) }
+            }
             if (WearProxyCapability.SessionSelectionLookup in capabilities) {
               selectedSessionKey?.takeIf(String::isNotBlank)?.let { put("selectedSessionKey", it) }
             }
@@ -394,6 +407,8 @@ internal class WearGatewayRepository(
       phoneNodeId = response.sourceNodeId,
       activeAgentId = result.string("activeAgentId"),
       selectedSessionValid = result.boolean("selectedSessionValid") ?: false,
+      hasMore = result.boolean("hasMore") ?: false,
+      nextOffset = result.long("nextOffset")?.toInt(),
     )
   }
 
diff --git a/apps/android/wear/src/main/java/ai/openclaw/wear/WearScreens.kt b/apps/android/wear/src/main/java/ai/openclaw/wear/WearScreens.kt
index 851c5f3786b8..a37ccf9e1e8b 100644
--- a/apps/android/wear/src/main/java/ai/openclaw/wear/WearScreens.kt
+++ b/apps/android/wear/src/main/java/ai/openclaw/wear/WearScreens.kt
@@ -166,6 +166,11 @@ internal fun OpenClawWearScreens(
   onSelectAgent: (String) -> Unit,
   onSelectSession: (String) -> Unit,
   onSelectModel: (String) -> Unit,
+  onSearchSessions: () -> Unit = {},
+  onLoadMoreSessionSearch: () -> Unit = {},
+  onClearSessionSearch: () -> Unit = {},
+  onSearchModels: () -> Unit = {},
+  onClearModelSearch: () -> Unit = {},
   onAgentPulseVisibilityChanged: (Boolean) -> Unit = {},
   onAgentPulseRefresh: () -> Unit = {},
   onRefresh: () -> Unit,
@@ -299,6 +304,11 @@ internal fun OpenClawWearScreens(
             onSelectAgent = onSelectAgent,
             onSelectSession = onSelectSession,
             onSelectModel = onSelectModel,
+            onSearchSessions = onSearchSessions,
+            onLoadMoreSessionSearch = onLoadMoreSessionSearch,
+            onClearSessionSearch = onClearSessionSearch,
+            onSearchModels = onSearchModels,
+            onClearModelSearch = onClearModelSearch,
             onSpeakLatest = onSpeakLatest,
             onStopSpeaking = onStopSpeaking,
           )
@@ -372,6 +382,11 @@ private fun ChatPage(
   onSelectAgent: (String) -> Unit,
   onSelectSession: (String) -> Unit,
   onSelectModel: (String) -> Unit,
+  onSearchSessions: () -> Unit,
+  onLoadMoreSessionSearch: () -> Unit,
+  onClearSessionSearch: () -> Unit,
+  onSearchModels: () -> Unit,
+  onClearModelSearch: () -> Unit,
   onSpeakLatest: () -> Unit,
   onStopSpeaking: () -> Unit,
 ) {
@@ -385,8 +400,6 @@ private fun ChatPage(
       visibleMessageCount = visibleMessages.size,
       hasStreaming = streamingText != null,
       canAbort = canAbort,
-      hasAssistant = hasAssistant,
-      hasFailure = snapshot.failure != null,
     )
   val contentRevision =
     wearChatContentRevision(
@@ -396,6 +409,25 @@ private fun ChatPage(
       latestAnchorIndex = latestAnchorIndex,
     )
   var followState by remember(snapshot.activeSessionId) { mutableStateOf(WearThreadFollowState()) }
+  var contextPicker by remember { mutableStateOf<WearContextPicker?>(null) }
+
+  fun clearContextPickerSearch() {
+    when (contextPicker) {
+      WearContextPicker.Session -> onClearSessionSearch()
+      WearContextPicker.Model -> onClearModelSearch()
+      else -> Unit
+    }
+  }
+
+  fun finishContextPicker() {
+    clearContextPickerSearch()
+    contextPicker = null
+  }
+
+  fun closeContextPicker() {
+    clearContextPickerSearch()
+    contextPicker = contextPicker?.let(::wearContextPickerAfterClose)
+  }
 
   LaunchedEffect(listState, snapshot.activeSessionId) {
     snapshotFlow {
@@ -429,15 +461,6 @@ private fun ChatPage(
       pageLabel = stringResource(R.string.chat),
       listState = listState,
     ) {
-      item {
-        ConversationIdentity(
-          snapshot = snapshot,
-          actionBusy = actionBusy,
-          onSelectAgent = onSelectAgent,
-          onSelectSession = onSelectSession,
-          onSelectModel = onSelectModel,
-        )
-      }
       item {
         ConversationStatus(
           interaction = interaction,
@@ -445,28 +468,6 @@ private fun ChatPage(
           gatewayConnected = snapshot.gatewayState == WearGatewayState.CONNECTED,
         )
       }
-      item {
-        Row(
-          modifier =
-            Modifier
-              .fillMaxWidth()
-              .padding(horizontal = 12.dp),
-          horizontalArrangement = Arrangement.spacedBy(6.dp),
-        ) {
-          ActionButton(
-            label = stringResource(R.string.talk),
-            enabled = inputEnabled && !actionBusy && !speaking,
-            onClick = onTalk,
-            modifier = Modifier.weight(1f),
-          )
-          ActionButton(
-            label = stringResource(R.string.type),
-            enabled = inputEnabled && !actionBusy && !speaking,
-            onClick = onType,
-            modifier = Modifier.weight(1f),
-          )
-        }
-      }
       if (canAbort) {
         item {
           SecondaryButton(
@@ -492,6 +493,11 @@ private fun ChatPage(
           }
         }
       }
+      if (latestAnchorIndex >= 0) {
+        item(key = "chat-end") {
+          Spacer(modifier = Modifier.height(1.dp))
+        }
+      }
       if (hasAssistant) {
         item {
           SecondaryButton(
@@ -506,18 +512,42 @@ private fun ChatPage(
           )
         }
       }
+      item {
+        Row(
+          modifier =
+            Modifier
+              .fillMaxWidth()
+              .padding(horizontal = 12.dp),
+          horizontalArrangement = Arrangement.spacedBy(6.dp),
+        ) {
+          ActionButton(
+            label = stringResource(R.string.talk),
+            enabled = inputEnabled && !actionBusy && !speaking,
+            onClick = onTalk,
+            modifier = Modifier.weight(1f),
+          )
+          ActionButton(
+            label = stringResource(R.string.type),
+            enabled = inputEnabled && !actionBusy && !speaking,
+            onClick = onType,
+            modifier = Modifier.weight(1f),
+          )
+        }
+      }
+      item {
+        ConversationContextPicker(
+          snapshot = snapshot,
+          actionBusy = actionBusy,
+          onOpenContextPicker = { contextPicker = WearContextPicker.Session },
+        )
+      }
       snapshot.failure?.let { failure ->
         item {
           InlineError(text = failureDetail(failure))
         }
       }
-      if (latestAnchorIndex >= 0) {
-        item(key = "chat-end") {
-          Spacer(modifier = Modifier.height(1.dp))
-        }
-      }
     }
-    if (followState.hasNewContent) {
+    if (followState.hasNewContent && contextPicker == null) {
       NewMessagesAction(
         modifier =
           Modifier
@@ -532,6 +562,31 @@ private fun ChatPage(
         }
       }
     }
+    contextPicker?.let { picker ->
+      ContextPickerOverlay(
+        picker = picker,
+        snapshot = snapshot,
+        actionBusy = actionBusy,
+        onDismiss = ::closeContextPicker,
+        onOpenAgentPicker = { contextPicker = WearContextPicker.Agent },
+        onOpenModelPicker = { contextPicker = WearContextPicker.Model },
+        onSelectAgent = { agentId ->
+          onSelectAgent(agentId)
+          finishContextPicker()
+        },
+        onSelectSession = { sessionId ->
+          onSelectSession(sessionId)
+          finishContextPicker()
+        },
+        onSelectModel = { modelRef ->
+          onSelectModel(modelRef)
+          finishContextPicker()
+        },
+        onSearchSessions = onSearchSessions,
+        onLoadMoreSessionSearch = onLoadMoreSessionSearch,
+        onSearchModels = onSearchModels,
+      )
+    }
   }
 }
 
@@ -1201,13 +1256,11 @@ internal fun wearChatLatestAnchorIndex(
   visibleMessageCount: Int,
   hasStreaming: Boolean,
   canAbort: Boolean,
-  hasAssistant: Boolean,
-  hasFailure: Boolean,
 ): Int {
   if (visibleMessageCount == 0 && !hasStreaming) return -1
   return CHAT_FIXED_ITEM_COUNT +
     visibleMessageCount +
-    listOf(canAbort, hasStreaming, hasAssistant, hasFailure).count { it }
+    listOf(canAbort, hasStreaming).count { it }
 }
 
 internal fun wearThreadLatestAnchorIndex(
@@ -1409,6 +1462,7 @@ private fun ControlsPage(
   onGatewayEnabledChange: (Boolean) -> Unit,
 ) {
   val gatewayConnected = snapshot.gatewayState == WearGatewayState.CONNECTED
+
   WearPage(pageLabel = stringResource(R.string.controls)) {
     item {
       ConnectionPanel(snapshot = snapshot)
@@ -1843,66 +1897,284 @@ private fun OpenClawHeader(pageLabel: String) {
 }
 
 @Composable
-private fun ConversationIdentity(
+private fun ConversationContextPicker(
   snapshot: WearConversationSnapshot,
   actionBusy: Boolean,
+  onOpenContextPicker: () -> Unit,
+) {
+  val session = snapshot.sessions.firstOrNull(WearSessionSummary::selected) ?: snapshot.sessions.firstOrNull()
+  val agent = snapshot.agents.firstOrNull(WearAgentSummary::selected) ?: snapshot.agents.firstOrNull()
+  val model = snapshot.models.firstOrNull(WearModelSummary::selected)
+  val agentName =
+    listOfNotNull(
+      agent?.emoji?.takeIf(String::isNotBlank),
+      agent?.name ?: stringResource(R.string.agent),
+    ).joinToString(" ")
+  val modelName = model?.name ?: snapshot.selectedModelRef ?: stringResource(R.string.model)
+  ContextPickerOption(
+    title =
+      stringResource(
+        R.string.context_label_value,
+        stringResource(R.string.session),
+        session?.title ?: stringResource(R.string.current_session),
+      ),
+    detail =
+      stringResource(
+        R.string.context_label_value,
+        stringResource(R.string.agent),
+        agentName,
+      ),
+    status =
+      stringResource(
+        R.string.context_label_value,
+        stringResource(R.string.model),
+        modelName,
+      ),
+    selected = true,
+    enabled = !actionBusy,
+    onClick = onOpenContextPicker,
+    modifier = Modifier.padding(horizontal = 12.dp),
+  )
+}
+
+internal enum class WearContextPicker {
+  Agent,
+  Session,
+  Model,
+}
+
+internal fun wearContextPickerAfterClose(picker: WearContextPicker): WearContextPicker? =
+  when (picker) {
+    WearContextPicker.Agent, WearContextPicker.Model -> WearContextPicker.Session
+    WearContextPicker.Session -> null
+  }
+
+@Composable
+private fun ContextPickerOverlay(
+  picker: WearContextPicker,
+  snapshot: WearConversationSnapshot,
+  actionBusy: Boolean,
+  onDismiss: () -> Unit,
+  onOpenAgentPicker: () -> Unit,
+  onOpenModelPicker: () -> Unit,
   onSelectAgent: (String) -> Unit,
   onSelectSession: (String) -> Unit,
   onSelectModel: (String) -> Unit,
+  onSearchSessions: () -> Unit,
+  onLoadMoreSessionSearch: () -> Unit,
+  onSearchModels: () -> Unit,
 ) {
-  val agentIndex = snapshot.agents.indexOfFirst(WearAgentSummary::selected)
-  val sessionIndex = snapshot.sessions.indexOfFirst(WearSessionSummary::selected)
-  val modelIndex = snapshot.models.indexOfFirst(WearModelSummary::selected)
-  val agent = snapshot.agents.getOrNull(agentIndex) ?: snapshot.agents.firstOrNull()
-  val session = snapshot.sessions.getOrNull(sessionIndex) ?: snapshot.sessions.firstOrNull()
-  val model = snapshot.models.getOrNull(modelIndex)
-  Panel {
-    ContextPickerRow(
-      label = stringResource(R.string.agent),
-      value =
-        listOfNotNull(
-          agent?.emoji?.takeIf(String::isNotBlank),
-          agent?.name ?: stringResource(R.string.agent),
-        ).joinToString(" "),
-      previous =
-        snapshot.agents
-          .getOrNull(agentIndex - 1)
-          ?.takeIf { snapshot.agentControlsSupported && !actionBusy }
-          ?.let { previous -> ({ onSelectAgent(previous.id) }) },
-      next =
-        snapshot.agents
-          .getOrNull(if (agentIndex < 0) 0 else agentIndex + 1)
-          ?.takeIf { snapshot.agentControlsSupported && !actionBusy }
-          ?.let { next -> ({ onSelectAgent(next.id) }) },
-    )
-    ContextPickerRow(
-      label = stringResource(R.string.session),
-      value = session?.title ?: stringResource(R.string.current_session),
-      previous =
-        snapshot.sessions
-          .getOrNull(sessionIndex - 1)
-          ?.takeIf { !actionBusy }
-          ?.let { previous -> ({ onSelectSession(previous.id) }) },
-      next =
-        snapshot.sessions
-          .getOrNull(if (sessionIndex < 0) 0 else sessionIndex + 1)
-          ?.takeIf { !actionBusy }
-          ?.let { next -> ({ onSelectSession(next.id) }) },
-    )
-    ContextPickerRow(
-      label = stringResource(R.string.model),
-      value = model?.name ?: snapshot.selectedModelRef ?: stringResource(R.string.model),
-      previous =
-        snapshot.models
-          .getOrNull(modelIndex - 1)
-          ?.takeIf { snapshot.modelControlsSupported && !actionBusy }
-          ?.let { previous -> ({ onSelectModel(previous.ref) }) },
-      next =
-        snapshot.models
-          .getOrNull(if (modelIndex < 0) 0 else modelIndex + 1)
-          ?.takeIf { snapshot.modelControlsSupported && !actionBusy }
-          ?.let { next -> ({ onSelectModel(next.ref) }) },
+  BackHandler(onBack = onDismiss)
+  val pageLabel =
+    when (picker) {
+      WearContextPicker.Agent -> stringResource(R.string.agent)
+      WearContextPicker.Session -> stringResource(R.string.session)
+      WearContextPicker.Model -> stringResource(R.string.model)
+    }
+  WearPage(pageLabel = pageLabel) {
+    item {
+      SecondaryButton(
+        label = stringResource(R.string.close),
+        enabled = true,
+        onClick = onDismiss,
+      )
+    }
+    if (picker == WearContextPicker.Session) {
+      item {
+        val agent = snapshot.agents.firstOrNull(WearAgentSummary::selected) ?: snapshot.agents.firstOrNull()
+        val model = snapshot.models.firstOrNull(WearModelSummary::selected)
+        Panel {
+          ContextPickerRow(
+            label = stringResource(R.string.agent),
+            value =
+              listOfNotNull(
+                agent?.emoji?.takeIf(String::isNotBlank),
+                agent?.name ?: stringResource(R.string.agent),
+              ).joinToString(" "),
+            onClick = onOpenAgentPicker.takeIf { snapshot.agentControlsSupported && !actionBusy },
+          )
+          ContextPickerDivider()
+          ContextPickerRow(
+            label = stringResource(R.string.model),
+            value = model?.name ?: snapshot.selectedModelRef ?: stringResource(R.string.model),
+            onClick = onOpenModelPicker.takeIf { snapshot.modelControlsSupported && !actionBusy },
+          )
+        }
+      }
+      if (snapshot.sessionSearchSupported) {
+        item {
+          SecondaryButton(
+            label = stringResource(R.string.search_sessions),
+            enabled = !actionBusy,
+            onClick = onSearchSessions,
+          )
+        }
+        snapshot.sessionSearchQuery?.let { query ->
+          item { PickerQueryLabel(query = query) }
+        }
+      }
+    }
+    if (picker == WearContextPicker.Model && snapshot.modelSearchSupported) {
+      item {
+        SecondaryButton(
+          label = stringResource(R.string.search_models),
+          enabled = !actionBusy,
+          onClick = onSearchModels,
+        )
+      }
+      snapshot.modelSearchQuery?.let { query ->
+        item { PickerQueryLabel(query = query) }
+      }
+    }
+    when (picker) {
+      WearContextPicker.Agent ->
+        snapshot.agents.forEach { agent ->
+          item(key = "agent:${agent.id}") {
+            ContextPickerOption(
+              title = listOfNotNull(agent.emoji?.takeIf(String::isNotBlank), agent.name).joinToString(" "),
+              detail = agent.id,
+              status = null,
+              selected = agent.selected,
+              enabled = !actionBusy,
+              onClick = { onSelectAgent(agent.id) },
+            )
+          }
+        }
+      WearContextPicker.Session -> {
+        val sessions =
+          if (snapshot.sessionSearchQuery == null) snapshot.sessions else snapshot.sessionSearchResults
+        if (sessions.isEmpty()) {
+          item { PickerEmptyResult() }
+        }
+        sessions.forEach { session ->
+          item(key = "session:${session.id}") {
+            val status =
+              listOfNotNull(
+                stringResource(R.string.active_on_phone).takeIf { session.activeOnPhone },
+                stringResource(R.string.open_on_watch).takeIf { session.openOnWatch },
+              ).joinToString(" / ").takeIf(String::isNotEmpty)
+            ContextPickerOption(
+              title = session.title ?: stringResource(R.string.current_session),
+              detail = null,
+              status = status,
+              selected = session.openOnWatch,
+              enabled = !actionBusy,
+              onClick = { onSelectSession(session.id) },
+            )
+          }
+        }
+        if (
+          snapshot.sessionSearchSupported &&
+          snapshot.sessionSearchQuery != null &&
+          snapshot.sessionSearchHasMore
+        ) {
+          item {
+            SecondaryButton(
+              label = stringResource(R.string.load_more),
+              enabled = !actionBusy,
+              onClick = onLoadMoreSessionSearch,
+            )
+          }
+        }
+      }
+      WearContextPicker.Model -> {
+        val models =
+          if (snapshot.modelSearchQuery == null) snapshot.models else snapshot.modelSearchResults
+        if (models.isEmpty()) {
+          item { PickerEmptyResult() }
+        }
+        models.forEach { model ->
+          item(key = "model:${model.ref}") {
+            ContextPickerOption(
+              title = model.name,
+              detail = model.ref,
+              status = null,
+              selected = model.selected,
+              enabled = !actionBusy,
+              onClick = { onSelectModel(model.ref) },
+            )
+          }
+        }
+      }
+    }
+  }
+}
+
+@Composable
+private fun PickerQueryLabel(query: String) {
+  Text(
+    text = query,
+    color = OpenClawWearTheme.colors.textMuted,
+    fontSize = 11.sp,
+    maxLines = 1,
+    overflow = TextOverflow.Ellipsis,
+  )
+}
+
+@Composable
+private fun PickerEmptyResult() {
+  Text(
+    text = stringResource(R.string.no_matches),
+    color = OpenClawWearTheme.colors.textMuted,
+    fontSize = 12.sp,
+    textAlign = TextAlign.Center,
+  )
+}
+
+@Composable
+private fun ContextPickerOption(
+  title: String,
+  detail: String?,
+  status: String?,
+  selected: Boolean,
+  enabled: Boolean,
+  onClick: () -> Unit,
+  modifier: Modifier = Modifier,
+) {
+  val colors = OpenClawWearTheme.colors
+  Column(
+    modifier =
+      modifier
+        .fillMaxWidth()
+        .padding(horizontal = 12.dp)
+        .clickable(enabled = enabled, role = Role.Button, onClick = onClick)
+        .then(
+          Modifier.border(
+            width = 1.dp,
+            color = if (selected) colors.primary else colors.border,
+            shape = RoundedCornerShape(14.dp),
+          ),
+        ).padding(horizontal = 12.dp, vertical = 9.dp),
+    horizontalAlignment = Alignment.CenterHorizontally,
+  ) {
+    Text(
+      text = title,
+      color = if (enabled) colors.text else colors.textMuted,
+      fontSize = 12.sp,
+      fontWeight = FontWeight.SemiBold,
+      textAlign = TextAlign.Center,
+      maxLines = 2,
+      overflow = TextOverflow.Ellipsis,
     )
+    detail?.takeIf(String::isNotBlank)?.let {
+      Text(
+        text = it,
+        color = colors.textMuted,
+        fontSize = 9.sp,
+        textAlign = TextAlign.Center,
+        maxLines = 1,
+        overflow = TextOverflow.Ellipsis,
+      )
+    }
+    status?.let {
+      Text(
+        text = it,
+        color = colors.primary,
+        fontSize = 9.sp,
+        fontWeight = FontWeight.Bold,
+        textAlign = TextAlign.Center,
+      )
+    }
   }
 }
 
@@ -1910,80 +2182,50 @@ private fun ConversationIdentity(
 private fun ContextPickerRow(
   label: String,
   value: String,
-  previous: (() -> Unit)?,
-  next: (() -> Unit)?,
+  onClick: (() -> Unit)?,
 ) {
-  Row(
-    modifier = Modifier.fillMaxWidth(),
-    verticalAlignment = Alignment.CenterVertically,
+  val colors = OpenClawWearTheme.colors
+  val enabled = onClick != null
+  Column(
+    modifier =
+      Modifier
+        .fillMaxWidth()
+        .clickable(
+          enabled = enabled,
+          role = Role.Button,
+          onClick = { onClick?.invoke() },
+        ).padding(vertical = 7.dp),
+    horizontalAlignment = Alignment.CenterHorizontally,
   ) {
-    PickerChevron(
-      glyph = "‹",
-      contentDescription = stringResource(R.string.previous_item, label),
-      onClick = previous,
+    Text(
+      text = localizedWearUppercase(label),
+      color = colors.textMuted,
+      fontSize = 10.sp,
+      fontWeight = FontWeight.Bold,
+      letterSpacing = 0.8.sp,
+      maxLines = 1,
     )
-    Column(
-      modifier = Modifier.weight(1f),
-      horizontalAlignment = Alignment.CenterHorizontally,
-    ) {
-      Text(
-        text = localizedWearUppercase(label),
-        color = OpenClawWearTheme.colors.textMuted,
-        fontSize = 10.sp,
-        fontWeight = FontWeight.Bold,
-        letterSpacing = 0.8.sp,
-        maxLines = 1,
-      )
-      Text(
-        text = value,
-        color = OpenClawWearTheme.colors.text,
-        fontSize = 12.sp,
-        fontWeight = FontWeight.SemiBold,
-        textAlign = TextAlign.Center,
-        maxLines = 1,
-        overflow = TextOverflow.Ellipsis,
-      )
-    }
-    PickerChevron(
-      glyph = "›",
-      contentDescription = stringResource(R.string.next_item, label),
-      onClick = next,
+    Text(
+      text = value,
+      color = if (enabled) colors.text else colors.textMuted,
+      fontSize = 12.sp,
+      fontWeight = FontWeight.SemiBold,
+      textAlign = TextAlign.Center,
+      maxLines = 1,
+      overflow = TextOverflow.Ellipsis,
     )
   }
 }
 
 @Composable
-private fun PickerChevron(
-  glyph: String,
-  contentDescription: String,
-  onClick: (() -> Unit)?,
-) {
-  val colors = OpenClawWearTheme.colors
-  val enabled = onClick != null
+private fun ContextPickerDivider() {
   Box(
     modifier =
       Modifier
-        // Foundation clickable expands hit testing to the system minimum touch target.
-        // Compact visual bounds keep picker values readable on 192dp round screens.
-        .width(32.dp)
-        .height(30.dp)
-        .semantics { this.contentDescription = contentDescription }
-        .clickable(
-          enabled = enabled,
-          role = Role.Button,
-          onClick = { onClick?.invoke() },
-        ),
-    contentAlignment = Alignment.Center,
-  ) {
-    Text(
-      text = glyph,
-      color = if (enabled) colors.primary else colors.textMuted.copy(alpha = 0.42f),
-      fontSize = 24.sp,
-      lineHeight = 24.sp,
-      fontWeight = FontWeight.SemiBold,
-      textAlign = TextAlign.Center,
-    )
-  }
+        .fillMaxWidth()
+        .height(1.dp)
+        .background(OpenClawWearTheme.colors.borderStrong.copy(alpha = 0.45f)),
+  )
 }
 
 @Composable
@@ -2498,6 +2740,6 @@ private fun failureDetail(failure: WearConversationFailure?): String =
     -> stringResource(R.string.try_again)
   }
 
-private const val CHAT_FIXED_ITEM_COUNT = 4
+private const val CHAT_FIXED_ITEM_COUNT = 2
 private const val VISIBLE_MESSAGE_COUNT = 8
 private const val VISIBLE_REALTIME_ENTRY_COUNT = 6
diff --git a/apps/android/wear/src/main/java/ai/openclaw/wear/WearViewModel.kt b/apps/android/wear/src/main/java/ai/openclaw/wear/WearViewModel.kt
index 8c997c524d88..534c4cb515f5 100644
--- a/apps/android/wear/src/main/java/ai/openclaw/wear/WearViewModel.kt
+++ b/apps/android/wear/src/main/java/ai/openclaw/wear/WearViewModel.kt
@@ -34,6 +34,13 @@ internal data class WearUiState(
   val proxyCapabilities: Set<WearProxyCapability> = emptySet(),
   val sessions: List<WearSession> = emptyList(),
   val selectedSession: WearSession? = null,
+  val phoneActiveSessionKey: String? = null,
+  val sessionSearchQuery: String? = null,
+  val sessionSearchResults: List<WearSession> = emptyList(),
+  val sessionSearchHasMore: Boolean = false,
+  val sessionSearchNextOffset: Int? = null,
+  val modelSearchQuery: String? = null,
+  val modelSearchResults: List<WearModel> = emptyList(),
   val messages: List<WearChatMessage> = emptyList(),
   val streamText: String? = null,
   val activeRunId: String? = null,
@@ -63,6 +70,13 @@ internal fun WearUiState.resetForPhoneChange(): WearUiState =
     proxyCapabilities = emptySet(),
     sessions = emptyList(),
     selectedSession = null,
+    phoneActiveSessionKey = null,
+    sessionSearchQuery = null,
+    sessionSearchResults = emptyList(),
+    sessionSearchHasMore = false,
+    sessionSearchNextOffset = null,
+    modelSearchQuery = null,
+    modelSearchResults = emptyList(),
     messages = emptyList(),
     streamText = null,
     activeRunId = null,
@@ -85,6 +99,13 @@ internal fun WearUiState.switchAgentContext(agentId: String): WearUiState =
     activeAgentId = agentId,
     sessions = emptyList(),
     selectedSession = null,
+    phoneActiveSessionKey = null,
+    sessionSearchQuery = null,
+    sessionSearchResults = emptyList(),
+    sessionSearchHasMore = false,
+    sessionSearchNextOffset = null,
+    modelSearchQuery = null,
+    modelSearchResults = emptyList(),
     messages = emptyList(),
     streamText = null,
     activeRunId = null,
@@ -98,6 +119,12 @@ internal fun WearUiState.switchAgentContext(agentId: String): WearUiState =
 internal fun WearUiState.switchSessionContext(session: WearSession): WearUiState =
   copy(
     selectedSession = session,
+    sessionSearchQuery = null,
+    sessionSearchResults = emptyList(),
+    sessionSearchHasMore = false,
+    sessionSearchNextOffset = null,
+    modelSearchQuery = null,
+    modelSearchResults = emptyList(),
     messages = emptyList(),
     streamText = null,
     activeRunId = null,
@@ -125,6 +152,10 @@ internal fun WearUiState.switchModelContext(modelRef: String): WearUiState {
   )
 }
 
+internal fun WearUiState.containsModelRef(modelRef: String): Boolean =
+  models.any { model -> model.ref == modelRef } ||
+    modelSearchResults.any { model -> model.ref == modelRef }
+
 internal fun shouldAcceptWearTalkSnapshot(
   snapshot: WearRealtimeTalkSnapshot,
   attemptId: String?,
@@ -199,6 +230,7 @@ internal class WearViewModel(
   private val sendAttemptTracker = WearSendAttemptTracker()
   private val controlBusyOwner = WearControlBusyOwner()
   private var loadJob: Job? = null
+  private var sessionSearchJob: Job? = null
   private var phoneRouteGeneration = 0L
   private var agentPulsePollJob: Job? = null
   private var agentPulseVisible = false
@@ -299,6 +331,46 @@ internal class WearViewModel(
     restartAgentPulsePolling(forceLoading = true)
   }
 
+  fun searchSessions(query: String) {
+    if (WearProxyCapability.SessionSearchPagination !in mutableState.value.proxyCapabilities) return
+    val normalized = query.trim()
+    if (normalized.isEmpty()) return
+    loadSessionSearch(normalized, offset = 0, append = false)
+  }
+
+  fun loadMoreSessionSearch() {
+    val current = mutableState.value
+    if (WearProxyCapability.SessionSearchPagination !in current.proxyCapabilities) return
+    val query = current.sessionSearchQuery ?: return
+    val offset = current.sessionSearchNextOffset ?: return
+    if (!current.sessionSearchHasMore) return
+    loadSessionSearch(query, offset = offset, append = true)
+  }
+
+  fun clearSessionSearch() {
+    sessionSearchJob?.cancel()
+    mutableState.update {
+      it.copy(
+        sessionSearchQuery = null,
+        sessionSearchResults = emptyList(),
+        sessionSearchHasMore = false,
+        sessionSearchNextOffset = null,
+      )
+    }
+  }
+
+  fun searchModels(query: String) {
+    if (WearProxyCapability.ModelCatalogSearch !in mutableState.value.proxyCapabilities) return
+    val normalized = query.trim()
+    if (normalized.isEmpty()) return
+    mutableState.value.selectedSession?.let { session -> loadModels(session, normalized) }
+  }
+
+  fun clearModelSearch() {
+    cancelModelLoad()
+    mutableState.update { it.copy(modelSearchQuery = null, modelSearchResults = emptyList()) }
+  }
+
   fun closeSession() {
     endRealtimeTalkForNavigation()
     cancelModelLoad()
@@ -491,7 +563,7 @@ internal class WearViewModel(
       current.realtimeCapturing ||
       current.realtimePlaying ||
       current.selectedModelRef == modelRef ||
-      current.models.none { model -> model.ref == modelRef } ||
+      !current.containsModelRef(modelRef) ||
       WearProxyCapability.ModelControls !in current.proxyCapabilities
     ) {
       return
@@ -586,6 +658,7 @@ internal class WearViewModel(
   }
 
   private fun loadSessions(expectedNodeId: String? = null) {
+    sessionSearchJob?.cancel()
     invalidateAgentPulse(clearSnapshot = true)
     cancelLoad()
     cancelModelLoad()
@@ -708,6 +781,13 @@ internal class WearViewModel(
               proxyCapabilities = status.capabilities,
               sessions = projectedSessions,
               selectedSession = selectedSession,
+              phoneActiveSessionKey = activeSessionKey,
+              sessionSearchQuery = null,
+              sessionSearchResults = emptyList(),
+              sessionSearchHasMore = false,
+              sessionSearchNextOffset = null,
+              modelSearchQuery = null,
+              modelSearchResults = emptyList(),
               messages = if (selectionChanged || !status.connected) emptyList() else it.messages,
               streamText = if (selectionChanged || !status.connected) null else it.streamText,
               activeRunId = if (selectionChanged || !status.connected) null else it.activeRunId,
@@ -834,11 +914,63 @@ internal class WearViewModel(
       }
   }
 
-  private fun loadModels(session: WearSession) {
+  private fun loadSessionSearch(
+    query: String,
+    offset: Int,
+    append: Boolean,
+  ) {
+    val current = mutableState.value
+    if (WearProxyCapability.SessionSearchPagination !in current.proxyCapabilities) return
+    val phoneNodeId = current.phoneNodeId ?: return
+    if (!current.connected) return
+    val routeGeneration = phoneRouteGeneration
+    sessionSearchJob?.cancel()
+    sessionSearchJob =
+      viewModelScope.launch {
+        try {
+          val result =
+            repository.sessions(
+              expectedNodeId = phoneNodeId,
+              capabilities = current.proxyCapabilities,
+              limit = 50,
+              offset = offset,
+              search = query,
+            )
+          if (routeGeneration != phoneRouteGeneration || mutableState.value.phoneNodeId != result.phoneNodeId) {
+            return@launch
+          }
+          mutableState.update { state ->
+            val results =
+              if (append && state.sessionSearchQuery == query) {
+                (state.sessionSearchResults + result.sessions).distinctBy(WearSession::key)
+              } else {
+                result.sessions
+              }
+            state.copy(
+              sessionSearchQuery = query,
+              sessionSearchResults = results,
+              sessionSearchHasMore = result.hasMore,
+              sessionSearchNextOffset = result.nextOffset,
+              failure = null,
+            )
+          }
+        } catch (err: CancellationException) {
+          throw err
+        } catch (err: Throwable) {
+          recordFailureForControlRoute(err, phoneNodeId, routeGeneration, loading = false)
+        }
+      }
+  }
+
+  private fun loadModels(
+    session: WearSession,
+    query: String? = null,
+  ) {
     val current = mutableState.value
     val capabilities = current.proxyCapabilities
     if (
       WearProxyCapability.ModelControls !in capabilities ||
+      (query != null && WearProxyCapability.ModelCatalogSearch !in capabilities) ||
       !wearSessionRequestIsCurrent(session, current.selectedSession, session.phoneNodeId)
     ) {
       return
@@ -853,6 +985,7 @@ internal class WearViewModel(
               expectedNodeId = session.phoneNodeId,
               capabilities = capabilities,
               selectedModelRef = session.modelRef,
+              query = query,
             )
           val selectedSession = mutableState.value.selectedSession
           if (!wearSessionRequestIsCurrent(session, selectedSession, modelList.phoneNodeId)) return@launch
@@ -871,7 +1004,11 @@ internal class WearViewModel(
             if (!wearSessionRequestIsCurrent(session, state.selectedSession, modelList.phoneNodeId)) {
               state
             } else {
-              state.copy(models = modelList.models)
+              if (query == null) {
+                state.copy(models = modelList.models, modelSearchQuery = null, modelSearchResults = emptyList())
+              } else {
+                state.copy(modelSearchQuery = query, modelSearchResults = modelList.models)
+              }
             }
           }
         } catch (err: CancellationException) {
diff --git a/apps/android/wear/src/main/res/values/strings.xml b/apps/android/wear/src/main/res/values/strings.xml
index 83091df3cfc4..6c360210fbf9 100644
--- a/apps/android/wear/src/main/res/values/strings.xml
+++ b/apps/android/wear/src/main/res/values/strings.xml
@@ -4,8 +4,6 @@
     <string name="chat">Chat</string>
     <string name="session">Session</string>
     <string name="model">Model</string>
-    <string name="previous_item">Previous %1$s</string>
-    <string name="next_item">Next %1$s</string>
     <string name="controls">Controls</string>
     <string name="talk">Talk</string>
     <string name="real_time_audio_failed">Watch audio failed</string>
@@ -43,6 +41,17 @@
     <string name="start_conversation">Start a conversation</string>
     <string name="start_conversation_detail">Talk or type on your watch. The paired phone sends the message through its authenticated OpenClaw session.</string>
     <string name="current_session">Current session</string>
+    <string name="context_label_value" tools:ignore="MissingTranslation">%1$s: %2$s</string>
+    <string name="close" tools:ignore="MissingTranslation">Close</string>
+    <string name="search" tools:ignore="MissingTranslation">Search</string>
+    <string name="search_sessions" tools:ignore="MissingTranslation">Search sessions</string>
+    <string name="search_models" tools:ignore="MissingTranslation">Search models</string>
+    <string name="load_more" tools:ignore="MissingTranslation">Load more</string>
+    <string name="active_on_phone" tools:ignore="MissingTranslation">Active on phone</string>
+    <string name="open_on_watch" tools:ignore="MissingTranslation">Open on watch</string>
+    <string name="no_matches" tools:ignore="MissingTranslation">No matches</string>
+    <string name="search_sessions_title" tools:ignore="MissingTranslation">Find a session</string>
+    <string name="search_models_title" tools:ignore="MissingTranslation">Find a model</string>
     <string name="appearance">Appearance</string>
     <string name="theme_dark">Dark</string>
     <string name="theme_light">Light</string>
diff --git a/apps/android/wear/src/test/java/ai/openclaw/wear/MainActivityTest.kt b/apps/android/wear/src/test/java/ai/openclaw/wear/MainActivityTest.kt
index d42a2094b111..f3533a8cf2e1 100644
--- a/apps/android/wear/src/test/java/ai/openclaw/wear/MainActivityTest.kt
+++ b/apps/android/wear/src/test/java/ai/openclaw/wear/MainActivityTest.kt
@@ -80,7 +80,7 @@ class MainActivityTest {
   @Test
   fun chatFollowTracksStreamingGrowthAtLatest() {
     val messages = listOf(WearChatMessage(id = "user-1", role = "user", text = "Status?", timestamp = 1L))
-    val anchor = wearChatLatestAnchorIndex(1, hasStreaming = true, canAbort = false, hasAssistant = false, hasFailure = false)
+    val anchor = wearChatLatestAnchorIndex(1, hasStreaming = true, canAbort = false)
     val first =
       nextWearThreadFollowForContent(
         state = WearThreadFollowState(),
@@ -131,21 +131,28 @@ class MainActivityTest {
   }
 
   @Test
-  fun chatFollowTargetsRenderedTrailingAnchor() {
+  fun chatFollowStopsAtLatestMessageBeforeControls() {
     assertEquals(
       -1,
-      wearChatLatestAnchorIndex(0, hasStreaming = false, canAbort = false, hasAssistant = false, hasFailure = true),
+      wearChatLatestAnchorIndex(0, hasStreaming = false, canAbort = false),
     )
     assertEquals(
-      5,
-      wearChatLatestAnchorIndex(1, hasStreaming = false, canAbort = false, hasAssistant = false, hasFailure = false),
+      3,
+      wearChatLatestAnchorIndex(1, hasStreaming = false, canAbort = false),
     )
     assertEquals(
-      10,
-      wearChatLatestAnchorIndex(2, hasStreaming = true, canAbort = true, hasAssistant = true, hasFailure = true),
+      6,
+      wearChatLatestAnchorIndex(2, hasStreaming = true, canAbort = true),
     )
   }
 
+  @Test
+  fun nestedContextPickerCloseReturnsToSessionPicker() {
+    assertEquals(WearContextPicker.Session, wearContextPickerAfterClose(WearContextPicker.Agent))
+    assertEquals(WearContextPicker.Session, wearContextPickerAfterClose(WearContextPicker.Model))
+    assertNull(wearContextPickerAfterClose(WearContextPicker.Session))
+  }
+
   @Test
   fun threadFollowTargetsTrailingAnchorAfterLatestContent() {
     assertEquals(-1, wearThreadLatestAnchorIndex(entryCount = 0, thinking = false))
@@ -254,17 +261,72 @@ class MainActivityTest {
         hasActiveRun = false,
         phoneNodeId = "phone-1",
       )
+    val phoneSession =
+      WearSession(
+        key = "session-2",
+        title = "Phone session",
+        updatedAt = 7,
+        hasActiveRun = false,
+        phoneNodeId = "phone-1",
+      )
     val snapshot =
       WearUiState(
         connected = true,
         phoneNodeId = "phone-1",
-        sessions = listOf(session),
+        phoneActiveSessionKey = phoneSession.key,
+        sessions = listOf(session, phoneSession),
         selectedSession = session,
         failure = WearConversationFailure.ACTION_REJECTED,
       ).toConversationSnapshot()
 
     assertEquals(WearConversationFailure.ACTION_REJECTED, snapshot?.failure)
-    assertNull(snapshot?.sessions?.single()?.title)
+    assertNull(snapshot?.sessions?.first()?.title)
+    assertFalse(snapshot?.sessions?.first()?.activeOnPhone == true)
+    assertTrue(snapshot?.sessions?.first()?.openOnWatch == true)
+    assertTrue(snapshot?.sessions?.last()?.activeOnPhone == true)
+    assertFalse(snapshot?.sessions?.last()?.openOnWatch == true)
+    assertEquals(phoneSession.key, snapshot?.phoneActiveSessionId)
+  }
+
+  @Test
+  fun modelSearchResultsRemainSelectableOutsideTheCompactModelWindow() {
+    val state =
+      WearUiState(
+        models = listOf(WearModel(ref = "openai/gpt-a", name = "GPT A")),
+        modelSearchResults =
+          listOf(WearModel(ref = "anthropic/claude", name = "Claude")),
+      )
+
+    assertTrue(state.containsModelRef("openai/gpt-a"))
+    assertTrue(state.containsModelRef("anthropic/claude"))
+    assertFalse(state.containsModelRef("google/gemini"))
+  }
+
+  @Test
+  fun pickerSearchVisibilityFollowsNegotiatedCapabilities() {
+    val legacySnapshot =
+      WearUiState(
+        phoneNodeId = "phone-1",
+        proxyCapabilities =
+          setOf(
+            WearProxyCapability.ModelControls,
+            WearProxyCapability.SessionSelectionLookup,
+          ),
+      ).toConversationSnapshot()
+    val currentSnapshot =
+      WearUiState(
+        phoneNodeId = "phone-1",
+        proxyCapabilities =
+          setOf(
+            WearProxyCapability.ModelCatalogSearch,
+            WearProxyCapability.SessionSearchPagination,
+          ),
+      ).toConversationSnapshot()
+
+    assertFalse(legacySnapshot?.modelSearchSupported == true)
+    assertFalse(legacySnapshot?.sessionSearchSupported == true)
+    assertTrue(currentSnapshot?.modelSearchSupported == true)
+    assertTrue(currentSnapshot?.sessionSearchSupported == true)
   }
 
   @Test
diff --git a/apps/android/wear/src/test/java/ai/openclaw/wear/WearGatewayRepositoryTest.kt b/apps/android/wear/src/test/java/ai/openclaw/wear/WearGatewayRepositoryTest.kt
index f7984b39f4b3..764734d1bbca 100644
--- a/apps/android/wear/src/test/java/ai/openclaw/wear/WearGatewayRepositoryTest.kt
+++ b/apps/android/wear/src/test/java/ai/openclaw/wear/WearGatewayRepositoryTest.kt
@@ -157,7 +157,7 @@ class WearGatewayRepositoryTest {
           when (method) {
             WearRpcMethod.SessionsList ->
               json.parseToJsonElement(
-                """{"sessions":[{"key":"agent:main","agentId":"main","displayName":"Main","updatedAt":7,"hasActiveRun":true,"modelRef":"openai/gpt-test"}],"activeAgentId":"main","selectedSessionValid":true}""",
+                """{"sessions":[{"key":"agent:main","agentId":"main","displayName":"Main","updatedAt":7,"hasActiveRun":true,"modelRef":"openai/gpt-test"}],"activeAgentId":"main","selectedSessionValid":true,"hasMore":true,"nextOffset":35}""",
               )
             WearRpcMethod.ChatHistory ->
               json.parseToJsonElement(
@@ -171,7 +171,13 @@ class WearGatewayRepositoryTest {
       val sessions =
         repository.sessions(
           selectedSessionKey = "agent:main",
-          capabilities = setOf(WearProxyCapability.SessionSelectionLookup),
+          offset = 5,
+          search = "older",
+          capabilities =
+            setOf(
+              WearProxyCapability.SessionSelectionLookup,
+              WearProxyCapability.SessionSearchPagination,
+            ),
         )
       val history = repository.history("agent:main", sessions.phoneNodeId)
 
@@ -189,7 +195,9 @@ class WearGatewayRepositoryTest {
       assertEquals("working", history.activeText)
       assertEquals("openai/gpt-test", history.selectedModelRef)
       assertEquals(7L, history.eventSequence)
-      assertEquals(setOf("limit", "selectedSessionKey"), requester.calls[0].second.keys)
+      assertTrue(sessions.hasMore)
+      assertEquals(35, sessions.nextOffset)
+      assertEquals(setOf("limit", "offset", "search", "selectedSessionKey"), requester.calls[0].second.keys)
       assertEquals(setOf("sessionKey", "limit", "maxChars"), requester.calls[1].second.keys)
     }
 
@@ -207,7 +215,7 @@ class WearGatewayRepositoryTest {
             WearRpcMethod.AgentsSelect -> JsonObject(emptyMap())
             WearRpcMethod.GatewayDisconnect ->
               json.parseToJsonElement(
-                """{"connected":false,"status":"Offline","activeAgentId":"main","selectedModelRef":"openai/gpt-test","capabilities":["agent-controls","gateway-controls","model-controls","session-selection-lookup","agent-pulse","attempt-scoped-realtime-audio"]}""",
+                """{"connected":false,"status":"Offline","activeAgentId":"main","selectedModelRef":"openai/gpt-test","capabilities":["agent-controls","gateway-controls","model-controls","model-catalog-search","session-selection-lookup","session-search-pagination","agent-pulse","attempt-scoped-realtime-audio"]}""",
               )
             else -> error("unexpected $method")
           }
@@ -275,7 +283,7 @@ class WearGatewayRepositoryTest {
       val requester =
         RecordingRequester { _, _ ->
           json.parseToJsonElement(
-            """{"connected":true,"status":"Connected","capabilities":["agent-controls","future-capability","gateway-controls","model-controls","session-selection-lookup","agent-pulse","attempt-scoped-realtime-audio"]}""",
+            """{"connected":true,"status":"Connected","capabilities":["agent-controls","future-capability","gateway-controls","model-controls","model-catalog-search","session-selection-lookup","session-search-pagination","agent-pulse","attempt-scoped-realtime-audio"]}""",
           )
         }
 
@@ -287,12 +295,14 @@ class WearGatewayRepositoryTest {
   @Test
   fun modelSelectionKeepsTheSelectedSessionAndUsesThePreferredPhone() =
     runTest {
-      val capabilities = setOf(WearProxyCapability.ModelControls)
+      val capabilities =
+        setOf(WearProxyCapability.ModelControls, WearProxyCapability.ModelCatalogSearch)
       val requester =
         RecordingRequester { method, params ->
           when (method) {
             WearRpcMethod.ModelsList -> {
               assertEquals("openai/gpt-a", params.getValue("selectedModelRef").jsonPrimitive.content)
+              assertEquals("anthropic", params.getValue("query").jsonPrimitive.content)
               json.parseToJsonElement(
                 """{"models":[{"ref":"openai/gpt-a","name":"GPT A"},{"ref":"openai/gpt-b","name":"GPT B"}]}""",
               )
@@ -309,7 +319,13 @@ class WearGatewayRepositoryTest {
         }
       val repository = WearGatewayRepository(requester)
 
-      val models = repository.models("phone-a", capabilities, selectedModelRef = "openai/gpt-a")
+      val models =
+        repository.models(
+          "phone-a",
+          capabilities,
+          selectedModelRef = "openai/gpt-a",
+          query = "anthropic",
+        )
       val selected =
         repository.selectModel(
           sessionKey = "agent:main:thread-7",
@@ -327,6 +343,40 @@ class WearGatewayRepositoryTest {
       assertTrue(requester.requirePreferredNodes.all { it })
     }
 
+  @Test
+  fun oldPhoneCapabilitiesDoNotReceivePickerSearchFields() =
+    runTest {
+      val requester =
+        RecordingRequester { method, params ->
+          when (method) {
+            WearRpcMethod.ModelsList -> {
+              assertEquals(setOf("selectedModelRef"), params.keys)
+              json.parseToJsonElement("""{"models":[]}""")
+            }
+            WearRpcMethod.SessionsList -> {
+              assertEquals(setOf("limit", "selectedSessionKey"), params.keys)
+              json.parseToJsonElement("""{"sessions":[]}""")
+            }
+            else -> error("unexpected $method")
+          }
+        }
+      val repository = WearGatewayRepository(requester)
+
+      repository.models(
+        expectedNodeId = "phone-a",
+        capabilities = setOf(WearProxyCapability.ModelControls),
+        selectedModelRef = "openai/gpt-a",
+        query = "anthropic",
+      )
+      repository.sessions(
+        expectedNodeId = "phone-a",
+        selectedSessionKey = "agent:main",
+        capabilities = setOf(WearProxyCapability.SessionSelectionLookup),
+        offset = 50,
+        search = "older",
+      )
+    }
+
   @Test
   fun chatEventPreservesReplaceAndTextOnlyMessage() {
     val event =

From 2fe6b678713fd1761adfffe8230822d58c4d89ae Mon Sep 17 00:00:00 2001
From: Dallin Romney <dallinromney@gmail.com>
Date: Fri, 21 Aug 2026 09:04:39 -0700
Subject: [PATCH 020/124] fix(test): read migrated Codex auth from shared owner
 (#127097)

---
 .../qa-lab/runtime/codex-auth-product-proof.test-support.ts   | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/test/e2e/qa-lab/runtime/codex-auth-product-proof.test-support.ts b/test/e2e/qa-lab/runtime/codex-auth-product-proof.test-support.ts
index 349a3ae7e59d..520e21b2aab7 100644
--- a/test/e2e/qa-lab/runtime/codex-auth-product-proof.test-support.ts
+++ b/test/e2e/qa-lab/runtime/codex-auth-product-proof.test-support.ts
@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import { expect } from "vitest";
-import { loadPersistedAuthProfileStore } from "../../../../src/agents/auth-profiles/persisted.js";
+import { loadPersistedSharedAuthProfileStore } from "../../../../src/agents/auth-profiles/persisted.js";
 import type { OpenClawTestInstance } from "../../../helpers/openclaw-test-instance.js";
 
 const OAUTH_PROFILE_ID = "openai:qa-oauth";
@@ -50,7 +50,7 @@ export async function runCodexAuthDoctorMigrationProof(
   });
   expect(doctor.code, doctor.stderr).toBe(0);
 
-  const canonicalStore = loadPersistedAuthProfileStore(instance.state.agentDir());
+  const canonicalStore = loadPersistedSharedAuthProfileStore(instance.env);
   const expectedProfiles: Record<string, Record<string, unknown>> = {
     [OAUTH_PROFILE_ID]: {
       type: "oauth",

From 8531da19930d71ab742411eef4be910c09a477ba Mon Sep 17 00:00:00 2001
From: Dallin Romney <dallinromney@gmail.com>
Date: Fri, 21 Aug 2026 09:05:05 -0700
Subject: [PATCH 021/124] fix(gateway): run transcript cursor E2E with full
 startup (#127094)

* test(gateway): publish runtime in agent E2Es

* test(gateway): leave replay fix to owner PR
---
 test/embedded-transcript-cursor.e2e.test.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/test/embedded-transcript-cursor.e2e.test.ts b/test/embedded-transcript-cursor.e2e.test.ts
index b6f61fe10a9e..5b9d5e611c6a 100644
--- a/test/embedded-transcript-cursor.e2e.test.ts
+++ b/test/embedded-transcript-cursor.e2e.test.ts
@@ -43,7 +43,10 @@ describe("embedded transcript cursor settlement", () => {
       const instance = await createOpenClawTestInstance({
         name: "embedded-transcript-cursor",
         config: createTestConfig(modelServer.baseUrl),
-        env: { OPENCLAW_SKIP_PROVIDERS: undefined },
+        env: {
+          OPENCLAW_SKIP_PROVIDERS: undefined,
+          OPENCLAW_TEST_MINIMAL_GATEWAY: undefined,
+        },
       });
       instances.push(instance);
       await instance.startGateway();

From 7085604a269deea4bb67754ec668a25b63c813ba Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 09:05:52 -0700
Subject: [PATCH 022/124] fix(ui): correct Automations row semantics (#127252)

Amp-Thread-ID: https://ampcode.com/threads/T-01a021f4-b547-7788-a916-d4a94cbd3e3b

Co-authored-by: Amp <amp@ampcode.com>
---
 ui/src/e2e/cron-remove.e2e.test.ts |  6 +++++-
 ui/src/pages/cron/view.test.ts     | 20 ++++++++++++++++++--
 ui/src/pages/cron/view.ts          | 20 ++++----------------
 ui/src/styles/cron.css             |  6 +++++-
 4 files changed, 32 insertions(+), 20 deletions(-)

diff --git a/ui/src/e2e/cron-remove.e2e.test.ts b/ui/src/e2e/cron-remove.e2e.test.ts
index f2d49f8008a6..9e734902b43b 100644
--- a/ui/src/e2e/cron-remove.e2e.test.ts
+++ b/ui/src/e2e/cron-remove.e2e.test.ts
@@ -63,7 +63,11 @@ suite.define(() => {
         expect(response?.status()).toBe(200);
         const row = page.locator(`[data-test-id="cron-row-${job.id}"]`);
         await row.waitFor({ state: "visible", timeout: 10_000 });
-        await row.locator(".cron-table__name-text").click();
+        expect(await page.locator(".cron-table__head").getAttribute("role")).toBeNull();
+        expect(await row.getAttribute("role")).toBeNull();
+        const openTask = row.getByRole("button", { name: /Nightly digest/ });
+        await openTask.focus();
+        await page.keyboard.press("Enter");
         const detail = page.locator('.cron-page[data-panel-mode="job"]');
         await detail.waitFor({ state: "visible" });
 
diff --git a/ui/src/pages/cron/view.test.ts b/ui/src/pages/cron/view.test.ts
index fed8803ff32b..2323d70f4e04 100644
--- a/ui/src/pages/cron/view.test.ts
+++ b/ui/src/pages/cron/view.test.ts
@@ -116,7 +116,22 @@ describe("cron view list pane", () => {
     expect(onJobsFiltersReset).toHaveBeenCalledTimes(1);
   });
 
-  it("renders table rows with schedule and status cells and selects on click", () => {
+  it("does not expose table rows without complete table semantics", () => {
+    const container = renderView({ jobs: [createJob("job-1")] });
+
+    for (const row of container.querySelectorAll('[role="row"]')) {
+      expect(row.closest('[role="table"], [role="grid"], [role="treegrid"]')).not.toBeNull();
+      expect(
+        Array.from(row.children).every((child) =>
+          child.matches(
+            '[role="cell"], [role="gridcell"], [role="columnheader"], [role="rowheader"]',
+          ),
+        ),
+      ).toBe(true);
+    }
+  });
+
+  it("renders table rows with independent native buttons for opening tasks", () => {
     const onSelectJob = vi.fn();
     const job = createJob("job-1", {
       trigger: { script: "json({ fire: true })" },
@@ -134,6 +149,7 @@ describe("cron view list pane", () => {
 
     const rows = Array.from(container.querySelectorAll(".cron-table__row"));
     expect(rows).toHaveLength(3);
+    expect(rows[0]?.getAttribute("role")).toBeNull();
     expect(rows[0]?.textContent).toContain("Cron 0 9 * * *");
     expect(rows[1]?.classList.contains("cron-table__row--paused")).toBe(true);
     expect(rows[1]?.textContent).toContain("Paused");
@@ -150,7 +166,7 @@ describe("cron view list pane", () => {
       "Trigger configured",
     );
 
-    (rows[1] as HTMLElement).click();
+    getElement(rows[1] as Element, ".cron-table__name", HTMLButtonElement).click();
     expect(onSelectJob).toHaveBeenCalledWith(paused);
   });
 
diff --git a/ui/src/pages/cron/view.ts b/ui/src/pages/cron/view.ts
index 5f3cb7b80067..1bad08ad1c1a 100644
--- a/ui/src/pages/cron/view.ts
+++ b/ui/src/pages/cron/view.ts
@@ -728,7 +728,7 @@ function renderJobsFilterPopover(props: CronProps, active: boolean) {
 function renderJobsTable(props: CronProps, hasAnyJobsFilters: boolean) {
   return html`
     <div class="cron-table ${props.canManage ? "" : "cron-table--read-only"}">
-      <div class="cron-table__head" role="row">
+      <div class="cron-table__head">
         <span>${t("cron.jobs.name")}</span>
         <span>${t("cron.jobs.schedule")}</span>
         <span>${t("cron.jobs.nextRun")}</span>
@@ -775,18 +775,10 @@ function renderJobRow(job: CronJob, props: CronProps) {
   return html`
     <div
       class="cron-table__row ${job.enabled ? "" : "cron-table__row--paused"}"
-      role="button"
-      tabindex="0"
       data-test-id=${`cron-row-${job.id}`}
       @click=${() => props.onSelectJob(job)}
-      @keydown=${(e: KeyboardEvent) => {
-        if (e.key === "Enter" || e.key === " ") {
-          e.preventDefault();
-          props.onSelectJob(job);
-        }
-      }}
     >
-      <span class="cron-table__name">
+      <button type="button" class="cron-table__name">
         ${renderJobStateIndicator(job)}
         <span class="cron-table__name-copy">
           <span class="cron-table__name-line">
@@ -814,17 +806,13 @@ function renderJobRow(job: CronJob, props: CronProps) {
               `
             : nothing}
         </span>
-      </span>
+      </button>
       ${renderJobCell("cron-table__schedule", t("cron.jobs.schedule"), formatCronSchedule(job))}
       ${renderJobCell("cron-table__next", t("cron.jobs.nextRun"), nextRun)}
       ${renderJobCell("cron-table__last", t("cron.jobs.lastRun"), renderLastRunCell(job))}
       ${props.canManage
         ? html`
-            <span
-              class="cron-table__actions"
-              @click=${(e: Event) => e.stopPropagation()}
-              @keydown=${(e: Event) => e.stopPropagation()}
-            >
+            <span class="cron-table__actions" @click=${(e: Event) => e.stopPropagation()}>
               <button
                 type="button"
                 class="btn btn--sm btn--ghost cron-row-run"
diff --git a/ui/src/styles/cron.css b/ui/src/styles/cron.css
index ab0d00741063..083dc729944e 100644
--- a/ui/src/styles/cron.css
+++ b/ui/src/styles/cron.css
@@ -324,7 +324,7 @@
 }
 
 .cron-table__row:hover,
-.cron-table__row:focus-visible {
+.cron-table__row:focus-within {
   background: var(--bg-hover);
 }
 
@@ -338,9 +338,13 @@
   align-items: flex-start;
   gap: 10px;
   min-width: 0;
+  padding: 0;
+  border: 0;
   color: var(--text-strong);
+  background: transparent;
   font-size: 13px;
   font-weight: 600;
+  text-align: left;
 }
 
 .cron-table__state {

From 566b0e53d5ab69c03137a2c9327e6242d6760159 Mon Sep 17 00:00:00 2001
From: Dallin Romney <dallinromney@gmail.com>
Date: Fri, 21 Aug 2026 09:10:10 -0700
Subject: [PATCH 023/124] fix(ai): retain compaction-only replay checkpoints
 (#127106)

* test(gateway): publish runtime in agent E2Es

* test(gateway): leave replay fix to owner PR

* fix(ai): retain compaction-only replay checkpoints

* fix(ai): preserve empty compaction replay checkpoints
---
 .../ai/src/transports/provider-compaction-replay.test.ts   | 7 +++++++
 packages/ai/src/transports/provider-compaction-replay.ts   | 5 ++++-
 test/gateway-openai-compaction-replay.e2e.test.ts          | 1 +
 3 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/packages/ai/src/transports/provider-compaction-replay.test.ts b/packages/ai/src/transports/provider-compaction-replay.test.ts
index 015de737bf1e..88b9733b26ef 100644
--- a/packages/ai/src/transports/provider-compaction-replay.test.ts
+++ b/packages/ai/src/transports/provider-compaction-replay.test.ts
@@ -110,6 +110,13 @@ describe("compaction replay owner rewrites", () => {
     expect(JSON.stringify(input)).toContain("full history prefix");
   });
 
+  it("keeps a compaction-only checkpoint through an unchanged empty-content projection", () => {
+    const owner = createAssistant([], 0);
+    const projected = replaceCompactionReplayOwnerContent(owner, []);
+
+    expect(projected.providerReplay).toBe(owner.providerReplay);
+  });
+
   it("keeps retained-user checkpoints independent of owner content indexes", () => {
     const retained = createAssistant([{ type: "text", text: "removed owner output" }], 0);
     const providerReplay = retained.providerReplay;
diff --git a/packages/ai/src/transports/provider-compaction-replay.ts b/packages/ai/src/transports/provider-compaction-replay.ts
index 6a6c95d2595b..f4bea6d73709 100644
--- a/packages/ai/src/transports/provider-compaction-replay.ts
+++ b/packages/ai/src/transports/provider-compaction-replay.ts
@@ -45,7 +45,10 @@ export function replaceCompactionReplayOwnerContent(
     return next;
   }
   const replayIndex = replay.replayIndex ?? 0;
-  if (content.length === 0 || replayIndex > message.content.length) {
+  if (
+    (content.length === 0 && message.content.length > 0) ||
+    replayIndex > message.content.length
+  ) {
     return stripCompactionReplayCheckpoint(next);
   }
   let sourceIndex = 0;
diff --git a/test/gateway-openai-compaction-replay.e2e.test.ts b/test/gateway-openai-compaction-replay.e2e.test.ts
index 356dd30fc581..1361c6274ab1 100644
--- a/test/gateway-openai-compaction-replay.e2e.test.ts
+++ b/test/gateway-openai-compaction-replay.e2e.test.ts
@@ -50,6 +50,7 @@ describe("Gateway OpenAI Responses compaction replay", () => {
         env: {
           OPENCLAW_DEBUG_MODEL_TRANSPORT: "1",
           OPENCLAW_SKIP_PROVIDERS: undefined,
+          OPENCLAW_TEST_MINIMAL_GATEWAY: undefined,
         },
       });
       instances.push(instance);

From ef91c818c4211b12720d83df47e833bc8f453822 Mon Sep 17 00:00:00 2001
From: Dallin Romney <dallinromney@gmail.com>
Date: Fri, 21 Aug 2026 09:10:48 -0700
Subject: [PATCH 024/124] fix(agents): preserve built plugin artifacts in
 prepared runtimes (#125957)

* fix(agents): preserve built plugin artifacts in prepared runtimes

* test(agents): update prepared runtime loader contract

* fix(agents): preserve built preference for deferred plugins

* fix(plugins): carry artifact preference through load context

* fix(plugins): keep artifact context optional

* test(plugins): prove prepared built artifact projection

* fix(agents): scope built artifacts to gateway runtimes

* test(agents): preserve standalone loader call shape

* fix(agents): retain prepared artifact choice on reuse

* test(plugins): update prepared load context expectation

Amp-Thread-ID: https://ampcode.com/threads/T-01a023b8-1041-7686-975f-c9f3ef91755d

---------

Co-authored-by: Amp <amp@ampcode.com>
---
 scripts/test-built-plugin-singleton.mts       | 40 +++++++++++--------
 src/agents/prepared-model-runtime.build.ts    |  4 +-
 src/agents/prepared-model-runtime.facts.ts    | 24 +++++++++--
 ...red-model-runtime.inbound-registry.test.ts |  4 ++
 ...prepared-model-runtime.inbound-registry.ts |  3 ++
 ...pared-model-runtime.plugin-context.test.ts | 20 ++++++----
 .../prepared-model-runtime.plugin-context.ts  |  5 ++-
 ...repared-model-runtime.plugin-generation.ts |  2 +
 src/agents/prepared-model-runtime.types.ts    |  2 +
 src/agents/runtime-plugins.test.ts            |  7 +++-
 src/agents/runtime-plugins.ts                 |  4 +-
 src/plugins/build-smoke-entry.ts              |  4 ++
 src/plugins/runtime/load-context.test.ts      |  3 ++
 src/plugins/runtime/load-context.ts           |  5 +++
 14 files changed, 96 insertions(+), 31 deletions(-)

diff --git a/scripts/test-built-plugin-singleton.mts b/scripts/test-built-plugin-singleton.mts
index bb7bf912c90c..4502cfc64f7e 100644
--- a/scripts/test-built-plugin-singleton.mts
+++ b/scripts/test-built-plugin-singleton.mts
@@ -15,11 +15,13 @@ const smokeEntryPath = path.join(repoRoot, "dist", "plugins", "build-smoke-entry
 assert.ok(fs.existsSync(smokeEntryPath), `missing build output: ${smokeEntryPath}`);
 
 const {
+  buildPluginRuntimeLoadOptions,
   clearPluginCommands,
   getPluginCommandSpecs,
   getPluginModuleLoaderStats,
   loadOpenClawPlugins,
   matchPluginCommand,
+  resolvePluginRuntimeLoadContext,
 } = await import(pathToFileURL(smokeEntryPath).href);
 
 assert.equal(typeof loadOpenClawPlugins, "function", "built loader export missing");
@@ -126,24 +128,28 @@ assert.equal(
 clearPluginCommands();
 
 const smsStatsBefore = getPluginModuleLoaderStats();
-const smsRegistry = loadOpenClawPlugins({
-  cache: false,
-  preferBuiltPluginArtifacts: true,
-  workspaceDir: tempRoot,
-  env: {
-    ...process.env,
-    OPENCLAW_BUNDLED_PLUGINS_DIR: path.join(repoRoot, "dist-runtime", "extensions"),
-  },
-  config: {
-    plugins: {
-      enabled: true,
-      allow: ["sms"],
-      entries: {
-        sms: { enabled: true },
+// Prepared runtimes carry this context into late, plugin-scoped loads. Prove that the load-options
+// projection retains the built-artifact choice instead of reopening source transformation.
+const smsRegistry = loadOpenClawPlugins(
+  buildPluginRuntimeLoadOptions(
+    resolvePluginRuntimeLoadContext({
+      config: {
+        plugins: {
+          enabled: true,
+          allow: ["sms"],
+          entries: { sms: { enabled: true } },
+        },
       },
-    },
-  },
-});
+      env: {
+        ...process.env,
+        OPENCLAW_BUNDLED_PLUGINS_DIR: path.join(repoRoot, "extensions"),
+      },
+      preferBuiltPluginArtifacts: true,
+      workspaceDir: tempRoot,
+    }),
+    { cache: false, onlyPluginIds: ["sms"] },
+  ),
+);
 const smsRecord = smsRegistry.plugins.find((entry: { id: string }) => entry.id === "sms");
 assert.ok(smsRecord, "SMS plugin missing from registry");
 assert.equal(smsRecord.status, "loaded", smsRecord.error ?? "SMS plugin failed to load");
diff --git a/src/agents/prepared-model-runtime.build.ts b/src/agents/prepared-model-runtime.build.ts
index 5c4225d2f083..7e8264982ee2 100644
--- a/src/agents/prepared-model-runtime.build.ts
+++ b/src/agents/prepared-model-runtime.build.ts
@@ -342,10 +342,12 @@ async function buildSnapshotBatch(
     const prepareInboundPluginRegistry = groupInputs.some((input) =>
       inboundPluginRegistryInputs.has(input),
     );
+    const preferBuiltPluginArtifacts =
+      pluginGeneration?.preferBuiltPluginArtifacts ?? prepareInboundPluginRegistry;
     const prepared = await prepareWorkspaceBuildGroup(
       groupInputs,
       catalogMode,
-      {},
+      { preferBuiltPluginArtifacts },
       prepareInboundPluginRegistry ? loadInboundPluginRegistry : undefined,
       pluginGeneration,
       pluginMetadataSnapshot,
diff --git a/src/agents/prepared-model-runtime.facts.ts b/src/agents/prepared-model-runtime.facts.ts
index d208e3fc1eef..8b46c07d9fc9 100644
--- a/src/agents/prepared-model-runtime.facts.ts
+++ b/src/agents/prepared-model-runtime.facts.ts
@@ -140,7 +140,10 @@ function prepareAgentFacts(
 export async function prepareWorkspaceBuildGroup(
   inputs: readonly PreparedModelRuntimeInput[],
   catalogMode: PreparedModelRuntimeCatalogMode,
-  options: { providerDiscoveryProviderIds?: readonly string[] } = {},
+  options: {
+    providerDiscoveryProviderIds?: readonly string[];
+    preferBuiltPluginArtifacts?: boolean;
+  } = {},
   loadInboundPluginRegistry?: PreparedInboundRegistryLoader,
   reusablePluginGeneration?: PreparedModelRuntimePluginGeneration,
   preparedPluginMetadataSnapshot?: PreparedModelRuntimePluginGeneration["pluginMetadataSnapshot"],
@@ -176,9 +179,23 @@ export async function prepareWorkspaceBuildGroup(
         inboundPluginRegistry: reusablePluginGeneration.inboundPluginRegistry,
         runtimePluginRegistry: reusablePluginGeneration.pluginRegistry,
       }
-    : prepareWorkspacePluginRegistries(input, pluginMetadataSnapshot, loadInboundPluginRegistry);
+    : prepareWorkspacePluginRegistries(
+        input,
+        pluginMetadataSnapshot,
+        loadInboundPluginRegistry,
+        options.preferBuiltPluginArtifacts === true,
+      );
   const runtimePluginMs = reusablePluginGeneration ? 0 : performance.now() - runtimePluginStartedAt;
-  prepareOwnedPluginLoadContext(input, env, runtimePluginRegistry, pluginMetadataSnapshot);
+  const preferBuiltPluginArtifacts =
+    reusablePluginGeneration?.preferBuiltPluginArtifacts ??
+    options.preferBuiltPluginArtifacts === true;
+  prepareOwnedPluginLoadContext(
+    input,
+    env,
+    runtimePluginRegistry,
+    pluginMetadataSnapshot,
+    preferBuiltPluginArtifacts,
+  );
   const prepare = async () => {
     const matchesStaticModelId = createStaticModelIdMatcher({
       manifestPlugins: pluginMetadataSnapshot.plugins,
@@ -386,6 +403,7 @@ export async function prepareWorkspaceBuildGroup(
       pluginMetadataSnapshot,
       preparedStaticProviderCatalog,
       providerStaticModels,
+      preferBuiltPluginArtifacts,
       reusablePluginGeneration,
       runtimePluginRegistry,
     });
diff --git a/src/agents/prepared-model-runtime.inbound-registry.test.ts b/src/agents/prepared-model-runtime.inbound-registry.test.ts
index aa1496ef70ea..f01006a357f2 100644
--- a/src/agents/prepared-model-runtime.inbound-registry.test.ts
+++ b/src/agents/prepared-model-runtime.inbound-registry.test.ts
@@ -16,6 +16,7 @@ import {
   registerPreparedModelRuntimePublicationListener,
   refreshPreparedModelRuntimeSnapshots,
 } from "./prepared-model-runtime.js";
+import { getPreparedPluginRuntimeLoadContext } from "./prepared-model-runtime.plugin-context.js";
 
 const mocks = getPreparedModelRuntimeMocks();
 
@@ -195,6 +196,9 @@ describe("prepared reply dispatch runtime", () => {
       pluginGeneration: configuredRuntimeBefore.pluginGeneration,
     });
     const dynamicSelectedBefore = dynamicLease.snapshot.pluginRegistry;
+    expect(getPreparedPluginRuntimeLoadContext(dynamicSelectedBefore)).toMatchObject({
+      preferBuiltPluginArtifacts: true,
+    });
     dynamicLease.release();
     expect(mocks.loadAgentRuntimePluginRegistryHandle).toHaveBeenCalledTimes(2);
     expect(dynamicPreparationRegistries.every(Boolean)).toBe(true);
diff --git a/src/agents/prepared-model-runtime.inbound-registry.ts b/src/agents/prepared-model-runtime.inbound-registry.ts
index 2c0161692106..8c602b0bc220 100644
--- a/src/agents/prepared-model-runtime.inbound-registry.ts
+++ b/src/agents/prepared-model-runtime.inbound-registry.ts
@@ -51,6 +51,7 @@ export function createPreparedInboundRegistryLoader(): PreparedInboundRegistryLo
       ...(input.workspaceDir ? { workspaceDir: input.workspaceDir } : {}),
       ...(input.allowGatewaySubagentBinding ? { allowGatewaySubagentBinding: true } : {}),
       metadataSnapshot,
+      preferBuiltPluginArtifacts: true,
     });
     registries.set(key, registry);
     return registry;
@@ -62,6 +63,7 @@ export function prepareWorkspacePluginRegistries(
   input: PreparedModelRuntimeInput,
   metadataSnapshot: PluginMetadataSnapshot,
   loadInboundRegistry?: PreparedInboundRegistryLoader,
+  preferBuiltPluginArtifacts = false,
 ): {
   runtimePluginRegistry?: PluginRegistry;
   inboundPluginRegistry?: PluginRegistry;
@@ -83,6 +85,7 @@ export function prepareWorkspacePluginRegistries(
           ...(input.workspaceDir ? { workspaceDir: input.workspaceDir } : {}),
           ...(input.allowGatewaySubagentBinding ? { allowGatewaySubagentBinding: true } : {}),
           metadataSnapshot,
+          ...(preferBuiltPluginArtifacts ? { preferBuiltPluginArtifacts: true } : {}),
           selections: input.runtimePluginSelections,
         })
       : inboundPluginRegistry;
diff --git a/src/agents/prepared-model-runtime.plugin-context.test.ts b/src/agents/prepared-model-runtime.plugin-context.test.ts
index 587c7bbf58a1..1570f26955e5 100644
--- a/src/agents/prepared-model-runtime.plugin-context.test.ts
+++ b/src/agents/prepared-model-runtime.plugin-context.test.ts
@@ -42,12 +42,13 @@ describe("prepared model runtime plugin metadata ownership", () => {
     try {
       for (const input of inputs) {
         const registry = createEmptyPluginRegistry();
-        expect(prepareOwnedPluginLoadContext(input, process.env, registry, gatewaySnapshot)).toBe(
-          gatewaySnapshot,
-        );
-        expect(getPreparedPluginRuntimeLoadContext(registry)?.metadataSnapshot).toBe(
-          gatewaySnapshot,
-        );
+        expect(
+          prepareOwnedPluginLoadContext(input, process.env, registry, gatewaySnapshot, true),
+        ).toBe(gatewaySnapshot);
+        expect(getPreparedPluginRuntimeLoadContext(registry)).toMatchObject({
+          metadataSnapshot: gatewaySnapshot,
+          preferBuiltPluginArtifacts: true,
+        });
         expect(
           withPreparedPluginGenerationScope({ input, pluginGeneration }, (snapshot) => snapshot),
         ).toBe(gatewaySnapshot);
@@ -71,6 +72,7 @@ describe("prepared model runtime plugin metadata ownership", () => {
     const resolveMetadata = vi
       .spyOn(pluginMetadata, "loadPluginMetadataSnapshot")
       .mockReturnValue(directSnapshot);
+    const registry = createEmptyPluginRegistry();
 
     try {
       expect(
@@ -81,9 +83,13 @@ describe("prepared model runtime plugin metadata ownership", () => {
             workspaceDir,
           },
           process.env,
-          undefined,
+          registry,
         ),
       ).toBe(directSnapshot);
+      expect(getPreparedPluginRuntimeLoadContext(registry)).toMatchObject({
+        metadataSnapshot: directSnapshot,
+        preferBuiltPluginArtifacts: false,
+      });
       expect(resolveMetadata).toHaveBeenCalledWith({
         config,
         env: process.env,
diff --git a/src/agents/prepared-model-runtime.plugin-context.ts b/src/agents/prepared-model-runtime.plugin-context.ts
index a181f25e60a2..5af021c1ae89 100644
--- a/src/agents/prepared-model-runtime.plugin-context.ts
+++ b/src/agents/prepared-model-runtime.plugin-context.ts
@@ -29,6 +29,7 @@ function preparePluginLoadContext(
   env: NodeJS.ProcessEnv,
   registry: PluginRegistry | undefined,
   metadataSnapshot: PluginMetadataSnapshot,
+  preferBuiltPluginArtifacts: boolean,
 ): PluginRuntimeLoadContext & { metadataSnapshot: PluginMetadataSnapshot } {
   const { config } = input;
   const workspaceDir = metadataSnapshot.workspaceDir ?? input.workspaceDir;
@@ -44,6 +45,7 @@ function preparePluginLoadContext(
       workspaceDir,
       metadataSnapshot: preparedMetadataSnapshot,
       manifestRegistry: metadataSnapshot.manifestRegistry,
+      preferBuiltPluginArtifacts,
     }),
     metadataSnapshot,
     installRecords: extractPluginInstallRecordsFromInstalledPluginIndex(metadataSnapshot.index),
@@ -61,9 +63,10 @@ export function prepareOwnedPluginLoadContext(
   env: NodeJS.ProcessEnv,
   registry: PluginRegistry | undefined,
   preparedMetadataSnapshot?: PluginMetadataSnapshot,
+  preferBuiltPluginArtifacts = false,
 ): PluginMetadataSnapshot {
   const metadataSnapshot = preparedMetadataSnapshot ?? resolveColdMetadataSnapshot(input, env);
-  preparePluginLoadContext(input, env, registry, metadataSnapshot);
+  preparePluginLoadContext(input, env, registry, metadataSnapshot, preferBuiltPluginArtifacts);
   return metadataSnapshot;
 }
 
diff --git a/src/agents/prepared-model-runtime.plugin-generation.ts b/src/agents/prepared-model-runtime.plugin-generation.ts
index 62bdc040c000..be43871c4757 100644
--- a/src/agents/prepared-model-runtime.plugin-generation.ts
+++ b/src/agents/prepared-model-runtime.plugin-generation.ts
@@ -17,6 +17,7 @@ export function createPreparedPluginGeneration(params: {
   pluginMetadataSnapshot: PreparedModelRuntimePluginGeneration["pluginMetadataSnapshot"];
   preparedStaticProviderCatalog: PreparedModelRuntimePluginGeneration["preparedStaticProviderCatalog"];
   providerStaticModels: PreparedModelRuntimePluginGeneration["providerStaticModels"];
+  preferBuiltPluginArtifacts?: boolean;
   reusablePluginGeneration?: PreparedModelRuntimePluginGeneration;
   runtimePluginRegistry: PreparedModelRuntimePluginGeneration["pluginRegistry"];
 }): PreparedModelRuntimePluginGeneration {
@@ -35,6 +36,7 @@ export function createPreparedPluginGeneration(params: {
     ...(params.inboundPluginRegistry
       ? { inboundPluginRegistry: params.inboundPluginRegistry }
       : {}),
+    ...(params.preferBuiltPluginArtifacts ? { preferBuiltPluginArtifacts: true } : {}),
     ...(params.mediaCapabilityProviders
       ? { mediaCapabilityProviders: params.mediaCapabilityProviders }
       : {}),
diff --git a/src/agents/prepared-model-runtime.types.ts b/src/agents/prepared-model-runtime.types.ts
index 4082179b0666..cc08bea573fd 100644
--- a/src/agents/prepared-model-runtime.types.ts
+++ b/src/agents/prepared-model-runtime.types.ts
@@ -26,6 +26,8 @@ export type PreparedModelRuntimePluginGeneration = Readonly<{
   configuredCatalogEntries: readonly ModelCatalogEntry[];
   pluginRegistry?: PluginRegistry;
   inboundPluginRegistry?: PluginRegistry;
+  /** Immutable artifact choice for every registry reuse in this generation. */
+  preferBuiltPluginArtifacts?: boolean;
 }>;
 
 export type PreparedModelRuntimeSnapshot = Readonly<{
diff --git a/src/agents/runtime-plugins.test.ts b/src/agents/runtime-plugins.test.ts
index 9380cf6d0282..9ff17434dc04 100644
--- a/src/agents/runtime-plugins.test.ts
+++ b/src/agents/runtime-plugins.test.ts
@@ -162,7 +162,7 @@ describe("agent runtime plugin registries", () => {
     });
   });
 
-  it("preserves the gateway startup scope and ordering", () => {
+  it("keeps an explicit metadata generation source-default without Gateway selection", () => {
     const config = {} as never;
     const metadataSnapshot = createMetadataSnapshot();
 
@@ -184,6 +184,9 @@ describe("agent runtime plugin registries", () => {
         channelPluginLoadIntent: "full",
       }),
     );
+    expect(hoisted.loadPluginRegistryHandle).toHaveBeenCalledWith(
+      expect.not.objectContaining({ preferBuiltPluginArtifacts: true }),
+    );
   });
 
   it("inherits the current request registry before process-wide startup metadata", () => {
@@ -242,6 +245,7 @@ describe("agent runtime plugin registries", () => {
       env,
       workspaceDir: "/tmp/agent-workspace",
       metadataSnapshot: snapshot as never,
+      preferBuiltPluginArtifacts: true,
     });
 
     expect(hoisted.resolveAgentRuntimePluginLoadPlan).toHaveBeenCalledWith({
@@ -261,6 +265,7 @@ describe("agent runtime plugin registries", () => {
       installRecords: {},
       manifestRegistry: snapshot.manifestRegistry,
       onlyPluginIds: ["codex", "memory-core"],
+      preferBuiltPluginArtifacts: true,
       runtimeOptions: undefined,
       workspaceDir: snapshot.workspaceDir,
     });
diff --git a/src/agents/runtime-plugins.ts b/src/agents/runtime-plugins.ts
index 2653adc2bca6..6d6fe5647d48 100644
--- a/src/agents/runtime-plugins.ts
+++ b/src/agents/runtime-plugins.ts
@@ -28,7 +28,8 @@ type AgentRuntimePluginRegistryParams = {
   /** Explicit base scope for hosts without a Gateway startup registry. */
   basePluginIds?: readonly string[];
   selections?: readonly AgentHarnessPluginSelection[];
-  /** Lifecycle-selected metadata. Omission selects one standalone cold generation. */
+  /** Lifecycle-owned selection; standalone/direct generations stay source-default. */
+  preferBuiltPluginArtifacts?: boolean;
   metadataSnapshot?: PluginMetadataSnapshot;
 };
 
@@ -63,6 +64,7 @@ function resolveAgentRuntimePluginRegistryLoad(params: AgentRuntimePluginRegistr
     ...(metadataSnapshot.discovery ? { discovery: metadataSnapshot.discovery } : {}),
     installRecords: extractPluginInstallRecordsFromInstalledPluginIndex(metadataSnapshot.index),
     manifestRegistry: metadataSnapshot.manifestRegistry,
+    ...(params.preferBuiltPluginArtifacts ? { preferBuiltPluginArtifacts: true } : {}),
     ...(workspaceDir ? { workspaceDir } : {}),
   };
   const requestPluginRegistry = getPluginRuntimeGatewayRequestScope()?.pluginRegistry;
diff --git a/src/plugins/build-smoke-entry.ts b/src/plugins/build-smoke-entry.ts
index 348c7db77128..a9ff5629c25c 100644
--- a/src/plugins/build-smoke-entry.ts
+++ b/src/plugins/build-smoke-entry.ts
@@ -3,3 +3,7 @@ export { clearPluginCommands, executePluginCommand, matchPluginCommand } from ".
 export { getPluginCommandSpecs } from "./command-specs.js";
 export { loadOpenClawPlugins, loadPluginRegistryHandle } from "./loader.js";
 export { getPluginModuleLoaderStats } from "./plugin-module-loader-cache.js";
+export {
+  buildPluginRuntimeLoadOptions,
+  resolvePluginRuntimeLoadContext,
+} from "./runtime/load-context.js";
diff --git a/src/plugins/runtime/load-context.test.ts b/src/plugins/runtime/load-context.test.ts
index 44e907049368..ff50a3f9ee80 100644
--- a/src/plugins/runtime/load-context.test.ts
+++ b/src/plugins/runtime/load-context.test.ts
@@ -136,6 +136,7 @@ describe("resolvePluginRuntimeLoadContext", () => {
       manifestRegistry,
       metadataSnapshot,
       installRecords: {},
+      preferBuiltPluginArtifacts: false,
     });
     expect(loadPluginMetadataSnapshotMock).toHaveBeenCalledWith({
       allowWorkspaceScopedCurrent: true,
@@ -314,6 +315,7 @@ describe("resolvePluginRuntimeLoadContext", () => {
     const context = resolvePluginRuntimeLoadContext({
       config: { plugins: {} },
       env: { HOME: "/tmp/openclaw-home" } as NodeJS.ProcessEnv,
+      preferBuiltPluginArtifacts: true,
       workspaceDir: "/explicit-workspace",
     });
 
@@ -332,6 +334,7 @@ describe("resolvePluginRuntimeLoadContext", () => {
       logger: context.logger,
       manifestRegistry,
       installRecords: {},
+      preferBuiltPluginArtifacts: true,
       cache: false,
       activate: false,
       onlyPluginIds: ["demo"],
diff --git a/src/plugins/runtime/load-context.ts b/src/plugins/runtime/load-context.ts
index 65ee63766eea..5989e46ea464 100644
--- a/src/plugins/runtime/load-context.ts
+++ b/src/plugins/runtime/load-context.ts
@@ -137,6 +137,7 @@ export type PluginRuntimeLoadContext = {
   manifestRegistry?: PluginManifestRegistry;
   metadataSnapshot?: PluginMetadataSnapshot;
   installRecords?: Record<string, PluginInstallRecord>;
+  preferBuiltPluginArtifacts?: boolean;
 };
 
 /** Runtime load option values that can be passed directly to plugin loading. */
@@ -150,6 +151,7 @@ type PluginRuntimeResolvedLoadValues = Pick<
   | "logger"
   | "manifestRegistry"
   | "installRecords"
+  | "preferBuiltPluginArtifacts"
 >;
 
 /** Options accepted while resolving plugin runtime load context. */
@@ -162,6 +164,7 @@ type PluginRuntimeLoadContextOptions = {
   logger?: PluginLogger;
   manifestRegistry?: PluginManifestRegistry;
   metadataSnapshot?: PluginMetadataSnapshot;
+  preferBuiltPluginArtifacts?: boolean;
 };
 
 /** Creates the default plugin runtime loader logger. */
@@ -262,6 +265,7 @@ export function resolvePluginRuntimeLoadContext(
     ...(finalManifestRegistry ? { manifestRegistry: finalManifestRegistry } : {}),
     ...(metadataSnapshot ? { metadataSnapshot } : {}),
     installRecords,
+    preferBuiltPluginArtifacts: options?.preferBuiltPluginArtifacts === true,
   };
 }
 
@@ -287,6 +291,7 @@ export function buildPluginRuntimeLoadOptionsFromValues(
     logger: values.logger,
     manifestRegistry: values.manifestRegistry,
     installRecords: values.installRecords,
+    preferBuiltPluginArtifacts: values.preferBuiltPluginArtifacts,
     ...overrides,
   };
 }

From 8091f7ceb34528f0d7271a5704197441e4df3ac5 Mon Sep 17 00:00:00 2001
From: Dallin Romney <dallinromney@gmail.com>
Date: Fri, 21 Aug 2026 09:11:17 -0700
Subject: [PATCH 025/124] test(qa): align failed-tool recovery oracle (#127077)

* test(qa): bound OTEL runtime timeout evidence

* test(qa): identify OTEL runtime wait stage

* test(qa): align failed-tool recovery oracle

* test(qa): bound recent OTEL trace evidence

* test(qa): keep trace summary type private
---
 .../runtime/otel-gateway-runtime.e2e.test.ts  | 11 +----
 .../qa-lab/runtime/otel-test-support.test.ts  | 31 +++++++++++++
 test/e2e/qa-lab/runtime/otel-test-support.ts  | 46 +++++++++++++++++++
 3 files changed, 79 insertions(+), 9 deletions(-)
 create mode 100644 test/e2e/qa-lab/runtime/otel-test-support.test.ts

diff --git a/test/e2e/qa-lab/runtime/otel-gateway-runtime.e2e.test.ts b/test/e2e/qa-lab/runtime/otel-gateway-runtime.e2e.test.ts
index c7d12f348c01..9fffd444af03 100644
--- a/test/e2e/qa-lab/runtime/otel-gateway-runtime.e2e.test.ts
+++ b/test/e2e/qa-lab/runtime/otel-gateway-runtime.e2e.test.ts
@@ -250,15 +250,8 @@ describe("diagnostics-otel gateway runtime", () => {
         },
         45_000,
         () => ({
-          requests: activeReceiver.capturedRequests,
-          spans: activeReceiver.capturedSpans.map((span) => ({
-            attributes: span.attributes,
-            name: span.name,
-            parentSpanId: span.parentSpanId,
-            spanId: span.spanId,
-            statusCode: span.statusCode,
-            traceId: span.traceId,
-          })),
+          requests: activeReceiver.capturedRequests.slice(-8),
+          traces: activeReceiver.recentTraceSummary(),
         }),
       );
 
diff --git a/test/e2e/qa-lab/runtime/otel-test-support.test.ts b/test/e2e/qa-lab/runtime/otel-test-support.test.ts
new file mode 100644
index 000000000000..357c43bc3c3d
--- /dev/null
+++ b/test/e2e/qa-lab/runtime/otel-test-support.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, test } from "vitest";
+import { type CapturedSpan, createRecentTraceSummary } from "./otel-test-support.js";
+
+function span(traceId: string, name: string): CapturedSpan {
+  return { attributes: {}, name, parent: false, traceId };
+}
+
+describe("recent OTLP trace summaries", () => {
+  test("retains the eight most recently active traces", () => {
+    const summary = createRecentTraceSummary();
+    summary.add(Array.from({ length: 9 }, (_, index) => span(`trace-${index}`, "started")));
+    summary.add([span("trace-0", "finished")]);
+
+    expect(summary.read()).toEqual([
+      ...Array.from({ length: 7 }, (_, index) => ({
+        traceId: `trace-${index + 2}`,
+        names: { started: 1 },
+      })),
+      { traceId: "trace-0", names: { finished: 1 } },
+    ]);
+  });
+
+  test("bounds distinct span names retained for each trace", () => {
+    const summary = createRecentTraceSummary();
+    summary.add(Array.from({ length: 20 }, (_, index) => span("trace", `span-${index}`)));
+
+    const [trace] = summary.read();
+    expect(Object.keys(trace!.names)).toHaveLength(16);
+    expect(trace!.names.other).toBe(5);
+  });
+});
diff --git a/test/e2e/qa-lab/runtime/otel-test-support.ts b/test/e2e/qa-lab/runtime/otel-test-support.ts
index 04ae2ef8a8c0..4bc834a1e713 100644
--- a/test/e2e/qa-lab/runtime/otel-test-support.ts
+++ b/test/e2e/qa-lab/runtime/otel-test-support.ts
@@ -73,6 +73,49 @@ export type CapturedLogRecord = {
   traceId: string;
 };
 
+type CapturedTraceSummary = {
+  traceId: string;
+  names: Record<string, number>;
+};
+
+const MAX_RECENT_TRACE_SUMMARIES = 8;
+const MAX_SPAN_NAMES_PER_TRACE_SUMMARY = 16;
+const OTHER_SPAN_NAME = "other";
+
+export function createRecentTraceSummary() {
+  const traces = new Map<string, Map<string, number>>();
+
+  return {
+    add(spans: readonly CapturedSpan[]): void {
+      for (const span of spans) {
+        const traceId = span.traceId || "missing";
+        const names = traces.get(traceId) ?? new Map<string, number>();
+        const name =
+          names.has(span.name) || names.size < MAX_SPAN_NAMES_PER_TRACE_SUMMARY - 1
+            ? span.name
+            : OTHER_SPAN_NAME;
+        names.set(name, (names.get(name) ?? 0) + 1);
+
+        // Map insertion order owns recency; reinserting keeps the latest active trace last.
+        traces.delete(traceId);
+        traces.set(traceId, names);
+        if (traces.size > MAX_RECENT_TRACE_SUMMARIES) {
+          const oldestTraceId = traces.keys().next().value;
+          if (oldestTraceId !== undefined) {
+            traces.delete(oldestTraceId);
+          }
+        }
+      }
+    },
+    read(): CapturedTraceSummary[] {
+      return [...traces].map(([traceId, names]) => ({
+        traceId,
+        names: Object.fromEntries(names),
+      }));
+    },
+  };
+}
+
 export function runModelCallAndCaptureTraceparent(params: {
   trace: DiagnosticTraceContext;
   runId: string;
@@ -672,6 +715,7 @@ export function startLocalOtlpReceiver(disallowedBodyNeedles: string[] = []) {
   const capturedMetrics: CapturedMetric[] = [];
   const capturedLogRecords: CapturedLogRecord[] = [];
   const capturedBodyText: Partial<Record<OtlpSignal, string[]>> = {};
+  const recentTraceSummary = createRecentTraceSummary();
   const sockets = new Set<Socket>();
   const server = createServer((req: IncomingMessage, res: ServerResponse) => {
     void (async () => {
@@ -736,6 +780,7 @@ export function startLocalOtlpReceiver(disallowedBodyNeedles: string[] = []) {
         return;
       }
       capturedSpans.push(...spans);
+      recentTraceSummary.add(spans);
       capturedMetrics.push(...metrics);
       capturedLogRecords.push(...logRecords);
       capturedRequests.push({
@@ -767,6 +812,7 @@ export function startLocalOtlpReceiver(disallowedBodyNeedles: string[] = []) {
     capturedMetrics,
     capturedLogRecords,
     capturedBodyText,
+    recentTraceSummary: recentTraceSummary.read,
     async listen(): Promise<number> {
       await new Promise<void>((resolve) => {
         server.listen(0, "127.0.0.1", resolve);

From a2f0b84e8adad3c29e11d6510809779963d748ee Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Fri, 21 Aug 2026 09:14:39 -0700
Subject: [PATCH 026/124] fix(release): report blockers before diagnostics
 finish (#127014)

* fix(release): separate decisions from diagnostic drain

* test(release): align decision drain fixtures

* fix(release): pin artifact downloads to valid v8 SHA

* fix(release): default empty evidence paths in plans

* fix(release): bind complete evidence reuse selection

* fix(release): harden retry artifact integrity

* fix(release): canonicalize reused validation evidence

* fix(release): bind manifest children to execution plan

* test(release): fix validation fixture types

* fix(release): retry transient decision artifact reads
---
 .agents/skills/openclaw-testing/SKILL.md      |   36 +-
 .agents/skills/release-openclaw-ci/SKILL.md   |   57 +-
 .github/workflows/full-release-validation.yml | 1089 ++++++--------
 docs/reference/RELEASING.md                   |   11 +
 docs/reference/full-release-validation.md     |   59 +-
 scripts/full-release-validation-at-sha.mts    |  155 +-
 scripts/full-release-validation-policy.d.mts  |   84 ++
 scripts/full-release-validation-policy.mjs    | 1019 +++++++++++++
 scripts/full-release-validation-state.d.mts   |   15 +
 scripts/full-release-validation-state.mjs     |  928 ++++++++++++
 scripts/release-ci-summary.mjs                |  465 +++++-
 test/scripts/ci-workflow-guards.test.ts       |    8 +-
 .../full-release-validation-at-sha.test.ts    |   82 +-
 .../full-release-validation-state.test.ts     | 1312 +++++++++++++++++
 ...ed-stable-full-validation-workflow.test.ts |   12 +-
 .../package-acceptance-workflow.test.ts       |  757 +++-------
 .../plugin-prerelease-test-plan.test.ts       |   81 +-
 test/scripts/release-ci-summary.test.ts       |  325 +++-
 test/scripts/release-no-push-workflow.test.ts |   51 +-
 19 files changed, 5179 insertions(+), 1367 deletions(-)
 create mode 100644 scripts/full-release-validation-policy.d.mts
 create mode 100644 scripts/full-release-validation-policy.mjs
 create mode 100644 scripts/full-release-validation-state.d.mts
 create mode 100644 scripts/full-release-validation-state.mjs
 create mode 100644 test/scripts/full-release-validation-state.test.ts

diff --git a/.agents/skills/openclaw-testing/SKILL.md b/.agents/skills/openclaw-testing/SKILL.md
index 6875624d919f..3f5899457966 100644
--- a/.agents/skills/openclaw-testing/SKILL.md
+++ b/.agents/skills/openclaw-testing/SKILL.md
@@ -340,16 +340,34 @@ lanes are intentionally reserved for the separate `Plugin Prerelease` child so
 PRs, main pushes, and ad hoc broad CI checks do not spend Docker/package time or
 all-plugin runtime time on release-only product coverage.
 
-Use one operator, one transition-only watcher, and at most one investigator for
-the current failed surface. Parent timeout or cancellation leaves adopted exact
-children running; cancel an exact child only by explicit operator action or the
-workflow's identity-mismatch/fail-fast path.
+Use one operator, one foreground owner, and at most one investigator for the
+current failed surface. Do not start `release-ci-summary --watch` while the
+SHA-pinned helper is already watching the same parent. Parent timeout or
+cancellation leaves adopted exact children running; cancel an exact child only
+by explicit operator action or by `fail_fast=true` after Release Decision binds
+the failure to that exact active run.
 
-The child-dispatch jobs record child run ids, and `Verify full validation`
-re-queries them during that parent attempt. A later narrow green run is useful
-recovery evidence but is not publish authorization by itself and there is no
-standalone finalizer. The release owner must reassess the recorded evidence and
-current publish gate.
+The child-dispatch jobs record run ID, run attempt, and URL, then finish. The
+parent seals those tuples, original dispatch titles, gate coverage, reuse
+policy, and original parent attempt in one immutable
+`full-release-execution-plan-<run-id>` artifact. Collector retries restore that
+artifact and adopt its children; they never reconstruct the plan or redispatch
+tests.
+`Release Decision` polls those exact identities and can report
+`blocked_diagnostics_running` before unrelated children finish.
+For reused evidence, it also repeats the canonical target, policy, changed-path,
+selected-run, root-run, and exact-child validation before it can pass.
+`Diagnostic Drain` continues every selected child to terminal with
+`fail_fast=false` unless the collector itself is cancelled or loses API
+access. `orchestration_error` permits collector recovery against the same
+exact children, never test redispatch. Diagnose `blocked_diagnostics_running`
+immediately, but wait for a terminal drain before retrying the failed surface.
+The final `Verify full validation` job consumes and validates the immutable
+execution plan plus the exact Decision and Drain artifacts instead of
+reclassifying child results. A
+later narrow green run is useful recovery evidence but is not publish
+authorization by itself and there is no standalone finalizer. The release owner
+must reassess the recorded evidence and current publish gate.
 
 Once the Code SHA is green, generate and commit only `CHANGELOG.md`. The new
 **Release SHA** is eligible for product-evidence reuse only when GitHub proves
diff --git a/.agents/skills/release-openclaw-ci/SKILL.md b/.agents/skills/release-openclaw-ci/SKILL.md
index d42d3a49c892..6ccf9e1d8ef9 100644
--- a/.agents/skills/release-openclaw-ci/SKILL.md
+++ b/.agents/skills/release-openclaw-ci/SKILL.md
@@ -48,9 +48,25 @@ Use this with `$release-openclaw-maintainer` and `$openclaw-testing` when a rele
   entitlement. Mandatory live providers must pass a real completion probe
   before release dispatch. Fix the credential first; do not add an alternate
   auth path merely to bypass a failed release credential.
-- Full Release Validation collects independent child failures to terminal
-  completion by default. Pass `fail_fast=true` only when the shorter
-  first-failure cancellation path is preferable.
+- Full Release Validation separates exact-child dispatch, Release Decision,
+  and Diagnostic Drain. With `fail_fast=false`, it makes zero child
+  cancellation calls; Diagnostic Drain follows every selected child to
+  terminal unless the collector itself is cancelled or loses GitHub API
+  access. With
+  `fail_fast=true`, Release Decision may cancel only the exact still-active
+  child that owns a blocking failure.
+- After dispatch, one immutable execution-plan artifact records the original
+  parent attempt, exact child tuples and titles, selected coverage, gates, and
+  reuse identity. Decision, Drain, manifest writing, evidence validation, and
+  final verification consume that plan. A collector retry restores it and
+  adopts the same children; missing plan state is an orchestration failure, not
+  permission to redispatch.
+- Reused evidence is not trusted merely because plan sealing found it. Release
+  Decision repeats the sealed target SHA, evidence SHA, policy, changed paths,
+  selected run, root run, source manifest, trusted tooling identity, and
+  exact-child checks before returning `passed`.
+- Parent retries select the newest Decision and Drain artifacts independently;
+  both must bind the same immutable plan even when their source attempts differ.
 - Use one release operator, one transition-only watcher, and at most one
   investigator for the current failed surface. Do not build audit-review-plan
   trees around a single workflow transition.
@@ -106,9 +122,10 @@ until their dependent enforcement changes land.
   - `stable-publish`: `release_profile=stable`
 - Keep at most one active parent for the same Validation SHA + Tooling SHA + rerun
   group. Concurrency does not cancel an older exact child automatically.
-- Parent cancellation or timeout leaves an adopted identity-checked child
-  running. The operator must cancel that exact child explicitly when it is no
-  longer useful.
+- Parent cancellation or timeout leaves adopted identity-checked children
+  running. The operator must cancel an exact child explicitly when it is no
+  longer useful. Do not infer a child identity from branch, title prefix, or
+  latest-run order.
 - Recover one failed surface with one diagnosis, one fix when needed, and one
   narrow retry. Then reassess the release decision. Do not automatically
   dispatch `rerun_group=all`.
@@ -268,6 +285,13 @@ Use the transition-only summary watcher instead of repeated raw polling:
 node scripts/release-ci-summary.mjs <full-release-run-id> --watch
 ```
 
+Do not start this watcher when the SHA-pinned helper is still the foreground
+owner. The helper reads the exact Release Decision artifact itself. On
+`blocked_diagnostics_running`, it exits nonzero immediately, keeps the temporary
+refs, and leaves Diagnostic Drain collecting the remaining terminal evidence.
+The watcher behaves the same way for separately dispatched parents: it reports
+the Release Decision blocker once and exits while the drain continues.
+
 For a one-shot snapshot:
 
 ```bash
@@ -278,6 +302,27 @@ node scripts/release-ci-summary.mjs <full-release-run-id>
 Diverged release-branch logs: `--first-parent` plus a bounded count.
 Stop watchers before ending the turn or switching strategy.
 
+Interpret state precisely:
+
+- `qualifying`: no decisive blocker yet; selected children are still active.
+- `blocked_diagnostics_running`: publication is blocked; Diagnostic Drain is
+  still collecting independent failures. Diagnose now, but do not retry until
+  the drain is terminal.
+- `passed`: all required policy and exact-child evidence passed.
+- `blocked_complete`: publication is blocked and all selected diagnostics are
+  terminal.
+- `orchestration_error`: GitHub API or collector failure prevented a verdict.
+  This is not a provenance mismatch. Recover the collector against the same
+  exact children; never redispatch tests to repair collection.
+- `cancelled_with_children`: the collector was cancelled while exact children
+  remained active.
+
+The `full-release-diagnostics-<run-id>-<attempt>` artifact is the terminal
+failure and timing manifest. Use it after an early blocker instead of
+restarting `all` merely to discover what the still-running children found.
+The stable `full-release-execution-plan-<run-id>` artifact is the identity
+source for every collector attempt.
+
 ## Failure Triage
 
 1. Confirm parent SHA and child run IDs.
diff --git a/.github/workflows/full-release-validation.yml b/.github/workflows/full-release-validation.yml
index dc1a82b8494d..c846b1ad6181 100644
--- a/.github/workflows/full-release-validation.yml
+++ b/.github/workflows/full-release-validation.yml
@@ -66,7 +66,7 @@ on:
         default: false
         type: boolean
       fail_fast:
-        description: Cancel each child workflow after its first failed job; false collects independent failures to completion
+        description: Cancel only an exact active child after its first blocking job; false drains all children to completion
         required: false
         default: false
         type: boolean
@@ -563,7 +563,7 @@ jobs:
   docker_runtime_assets_preflight:
     name: Verify Docker runtime image assets
     needs: [resolve_target, evidence_reuse]
-    if: ${{ always() && needs.resolve_target.result == 'success' && inputs.rerun_group == 'all' && needs.evidence_reuse.outputs.reuse != 'true' }}
+    if: ${{ always() && github.run_attempt == 1 && needs.resolve_target.result == 'success' && inputs.rerun_group == 'all' && needs.evidence_reuse.outputs.reuse != 'true' }}
     runs-on: ubuntu-24.04
     timeout-minutes: 20
     permissions:
@@ -589,7 +589,7 @@ jobs:
   prepare_release_candidate:
     name: Prepare shared release candidate
     needs: [resolve_target, evidence_reuse]
-    if: ${{ always() && needs.resolve_target.result == 'success' && needs.evidence_reuse.outputs.reuse != 'true' && inputs.release_package_spec == '' && inputs.package_acceptance_package_spec == '' && (contains(fromJSON('["all","plugin-prerelease","cross-os","package"]'), inputs.rerun_group) || (inputs.rerun_group == 'live-e2e' && needs.resolve_target.outputs.live_suite_filter == '')) }}
+    if: ${{ always() && github.run_attempt == 1 && needs.resolve_target.result == 'success' && needs.evidence_reuse.outputs.reuse != 'true' && inputs.release_package_spec == '' && inputs.package_acceptance_package_spec == '' && (contains(fromJSON('["all","plugin-prerelease","cross-os","package"]'), inputs.rerun_group) || (inputs.rerun_group == 'live-e2e' && needs.resolve_target.outputs.live_suite_filter == '')) }}
     permissions:
       actions: read
       contents: read
@@ -614,16 +614,15 @@ jobs:
   normal_ci:
     name: Run normal full CI
     needs: [resolve_target, evidence_reuse]
-    if: ${{ always() && needs.resolve_target.result == 'success' && contains(fromJSON('["all","ci"]'), inputs.rerun_group) && needs.evidence_reuse.outputs.reuse != 'true' }}
+    if: ${{ always() && github.run_attempt == 1 && needs.resolve_target.result == 'success' && contains(fromJSON('["all","ci"]'), inputs.rerun_group) && needs.evidence_reuse.outputs.reuse != 'true' }}
     runs-on: ubuntu-24.04
-    # The child owns lane timeouts; this monitor also covers queue delay and iOS.
-    timeout-minutes: 240
+    timeout-minutes: 15
     outputs:
       run_id: ${{ steps.dispatch.outputs.run_id }}
+      run_attempt: ${{ steps.dispatch.outputs.run_attempt }}
       url: ${{ steps.dispatch.outputs.url }}
-      conclusion: ${{ steps.dispatch.outputs.conclusion }}
     steps:
-      - name: Dispatch and monitor CI
+      - name: Dispatch CI
         id: dispatch
         env:
           GH_TOKEN: ${{ github.token }}
@@ -633,10 +632,8 @@ jobs:
           TARGET_SHA: ${{ needs.resolve_target.outputs.sha }}
           CHILD_WORKFLOW_REF: ${{ github.ref_name }}
           PARENT_WORKFLOW_SHA: ${{ github.sha }}
-          FAIL_FAST: ${{ inputs.fail_fast }}
         run: &full_release_child_dispatch |
           set -euo pipefail
-          FAIL_FAST="${FAIL_FAST:-false}"
 
           gh_with_retry() {
             local output status attempt
@@ -661,10 +658,6 @@ jobs:
             return "$status"
           }
 
-          fetch_child_run_json() {
-            gh_with_retry api "repos/${GITHUB_REPOSITORY}/actions/runs/${run_id}"
-          }
-
           validate_child_run() {
             local candidate_run_id="$1"
             local candidate_run_json attempt
@@ -711,71 +704,11 @@ jobs:
             return 1
           }
 
-          fetch_child_jobs() {
-            if [[ "$workflow" == "npm-telegram-beta-e2e.yml" || "$workflow" == "openclaw-performance.yml" ]]; then
-              gh_with_retry run view "$run_id" --json jobs --jq '.jobs[]'
-              return
-            fi
-            gh_with_retry api --paginate "repos/${GITHUB_REPOSITORY}/actions/runs/${run_id}/jobs?per_page=100" --jq '.jobs[]'
-          }
-
-          read_child_run_field() {
-            local field="$1"
-            if [[ "$workflow" == "npm-telegram-beta-e2e.yml" || "$workflow" == "openclaw-performance.yml" ]]; then
-              case "$field" in
-                html_url) field=url ;;
-              esac
-              gh_with_retry run view "$run_id" --json "$field" --jq ".${field} // \"\""
-              return
-            fi
-            fetch_child_run_json | jq -r ".${field} // \"\""
-          }
-
-          release_check_blocking_job() {
-            if [[ "$RELEASE_PROFILE" == "beta" && "$1" == "Run package acceptance / Telegram package acceptance / "* ]]; then
-              return 1
-            fi
-            case "$1" in
-              "resolve_target" | \
-              "Prepare release package artifact" | \
-              "install_smoke_release_checks / "* | \
-              "Run package acceptance" | \
-              "Run package acceptance / "*)
-                return 0
-                ;;
-            esac
-            return 1
-          }
-
-          release_checks_advisory_only() {
-            local run_json="$1"
-            local verifier_conclusion name saw_advisory failed
-            verifier_conclusion="$(
-              jq -r '.jobs[] | select(.name == "Verify release checks") | .conclusion' <<< "$run_json" |
-                tail -n 1
-            )"
-            if [[ "$verifier_conclusion" != "success" ]]; then
-              return 1
-            fi
-            saw_advisory=0
-            failed=0
-            while IFS= read -r name; do
-              [[ -z "${name// }" ]] && continue
-              if release_check_blocking_job "$name"; then
-                echo "::error::${name} is a package-safety Tideclaw alpha release-check lane."
-                failed=1
-              else
-                saw_advisory=1
-              fi
-            done < <(jq -r '.jobs[] | select(.conclusion != "success" and .conclusion != "skipped") | .name' <<< "$run_json")
-            [[ "$saw_advisory" == "1" && "$failed" == "0" ]]
-          }
-
-          dispatch_and_wait() {
+          dispatch_child() {
             local workflow="$1"
             local dispatch_run_name="$2"
             shift 2
-            local dispatch_output dispatch_status dispatch_run_ids matches_json match_count run_id status conclusion url poll_count run_json jobs_json child_head_sha encoded_workflow_ref current_workflow_sha expected_workflow_id started_epoch elapsed_seconds elapsed_minutes
+            local dispatch_output dispatch_status dispatch_run_ids matches_json match_count run_id run_json child_head_sha child_run_attempt url encoded_workflow_ref current_workflow_sha expected_workflow_id
 
             encoded_workflow_ref="$(jq -rn --arg value "$CHILD_WORKFLOW_REF" '$value | @uri')"
             current_workflow_sha="$(
@@ -838,147 +771,31 @@ jobs:
               exit 1
             fi
 
-            cancel_child() {
-              if [[ -n "${run_id:-}" ]]; then
-                echo "Cancelling child workflow ${workflow}: ${run_id}" >&2
-                gh run cancel "$run_id" >/dev/null 2>&1 || true
-              fi
-            }
             run_json="$(validate_child_run "$run_id")"
-            # Generic monitor failures and parent cancellation leave an
-            # identity-checked child running for explicit operator recovery.
             {
               echo "- Adopted child: \`${workflow}\` run \`${run_id}\`"
-              echo "- Parent cancellation leaves this child running; cancel it explicitly if no longer needed."
+              echo "- Release Decision owns blocking policy; Diagnostic Drain owns terminal collection."
             } >> "$GITHUB_STEP_SUMMARY"
 
             child_head_sha="$(jq -r '.head_sha // ""' <<< "$run_json")"
             if [[ "$child_head_sha" != "$PARENT_WORKFLOW_SHA" ]]; then
               echo "::error::${workflow} child run used workflow SHA ${child_head_sha}, expected parent workflow SHA ${PARENT_WORKFLOW_SHA}." >&2
-              cancel_child
               exit 1
             fi
 
             if [[ "$dispatch_status" -ne 0 ]]; then
               echo "::warning::${workflow} dispatch returned status ${dispatch_status}; adopted exact run ${run_id}." >&2
             fi
-            echo "Dispatched ${workflow}: https://github.com/${GITHUB_REPOSITORY}/actions/runs/${run_id}"
+            child_run_attempt="$(jq -r '.run_attempt // ""' <<< "$run_json")"
+            url="$(jq -r '.html_url // ""' <<< "$run_json")"
+            if [[ ! "$child_run_attempt" =~ ^[1-9][0-9]*$ || -z "${url// }" ]]; then
+              echo "::error::${workflow} child run omitted its attempt or URL." >&2
+              exit 1
+            fi
+            echo "Dispatched ${workflow}: ${url} (attempt ${child_run_attempt})"
             echo "run_id=${run_id}" >> "$GITHUB_OUTPUT"
-            started_epoch="$(date +%s)"
-
-            fail_fast_failed_jobs() {
-              if [[ "$FAIL_FAST" != "true" ]]; then
-                return 0
-              fi
-              local failed_jobs_json
-              if [[ "$workflow" == "openclaw-release-checks.yml" && "$CHILD_WORKFLOW_REF" =~ ^tideclaw/alpha/[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{4}Z$ ]]; then
-                return 0
-              fi
-              if [[ "$workflow" == "npm-telegram-beta-e2e.yml" ]]; then
-                failed_jobs_json="$(
-                  gh_with_retry run view "$run_id" --json jobs \
-                    --jq '[.jobs[] | select(.status == "completed" and .conclusion != "success" and .conclusion != "skipped")]'
-                )"
-              elif ! failed_jobs_json="$(
-                fetch_child_jobs |
-                  jq -s '[.[] | select(.status == "completed" and .conclusion != "success" and .conclusion != "skipped")]'
-              )"; then
-                echo "::warning::Could not list ${workflow} child jobs; continuing with authoritative workflow conclusion."
-                return 0
-              fi
-              if [[ "$workflow" == "openclaw-release-checks.yml" ]]; then
-                # Advisory QA jobs are owned by the child's status-artifact verifier.
-                failed_jobs_json="$(
-                  jq '[.[] | select(
-                    ((.name | startswith("Run QA Lab parity lane ("))
-                      or .name == "Run QA Lab parity report"
-                      or (.name | startswith("Run QA Lab runtime-pair lane ("))
-                      or .name == "Verify QA Lab runtime-pair lanes"
-                      or .name == "Run QA Lab live Discord lane"
-                      or .name == "Run QA Lab live WhatsApp lane"
-                      or .name == "Run QA Lab live Slack lane")
-                    | not)]' <<< "$failed_jobs_json"
-                )"
-                if [[ "$RELEASE_PROFILE" == "beta" ]]; then
-                  # Beta live-provider and Telegram package checks are advisory; repo E2E is blocking.
-                  failed_jobs_json="$(
-                    jq '[.[] | select(
-                      (((.name | startswith("Run repo/live E2E validation / "))
-                        and ((.name | contains("Docker live"))
-                          or (.name | contains("Live media suites"))
-                          or (.name | contains("validate_live_provider_suites"))
-                          or (.name | contains("validate_release_live_cache"))
-                          or (.name | contains("prepare_live_test_image"))))
-                        or (.name | startswith("Run package acceptance / Telegram package acceptance / ")))
-                      | not)]' <<< "$failed_jobs_json"
-                  )"
-                fi
-              fi
-              if jq -e 'length > 0' <<< "$failed_jobs_json" >/dev/null; then
-                if [[ "$workflow" == "npm-telegram-beta-e2e.yml" ]]; then
-                  echo "::error::npm-telegram-beta-e2e.yml has failed child jobs before the workflow completed; cancelling the remaining run."
-                else
-                  echo "::error::${workflow} has failed child jobs before the workflow completed; cancelling the remaining matrix."
-                fi
-                jq '.[] | {name, conclusion, url: (.url // .html_url)}' <<< "$failed_jobs_json"
-                cancel_child
-                exit 1
-              fi
-            }
-
-            poll_count=0
-            while true; do
-              status="$(read_child_run_field status)"
-              if [[ "$status" == "completed" ]]; then
-                break
-              fi
-              poll_count=$((poll_count + 1))
-              if (( poll_count % 5 == 0 )); then
-                fail_fast_failed_jobs
-                elapsed_seconds=$(( $(date +%s) - started_epoch ))
-                elapsed_minutes=$(( elapsed_seconds / 60 ))
-                echo "Still waiting on ${workflow} after ${elapsed_minutes}m: https://github.com/${GITHUB_REPOSITORY}/actions/runs/${run_id}"
-                fetch_child_jobs | jq 'select(.status != "completed") | {name, status, url: (.url // .html_url)}' || true
-              fi
-              sleep 60
-            done
-
-            if [[ "$workflow" == "openclaw-release-checks.yml" ]]; then
-              jobs_json="$(fetch_child_jobs | jq -s '{jobs: [.[] | {name, conclusion, url: .html_url}]}')"
-              run_json="$(
-                jq -s '.[0] + .[1]' \
-                  <(fetch_child_run_json | jq '{conclusion: (.conclusion // ""), url: .html_url}') \
-                  <(printf '%s\n' "$jobs_json")
-              )"
-              conclusion="$(jq -r '.conclusion' <<< "$run_json")"
-              url="$(jq -r '.url' <<< "$run_json")"
-            else
-              conclusion="$(read_child_run_field conclusion)"
-              url="$(read_child_run_field html_url)"
-            fi
-            echo "${workflow} finished with ${conclusion}: ${url}"
+            echo "run_attempt=${child_run_attempt}" >> "$GITHUB_OUTPUT"
             echo "url=${url}" >> "$GITHUB_OUTPUT"
-            echo "conclusion=${conclusion}" >> "$GITHUB_OUTPUT"
-            if [[ "$conclusion" == "success" ]]; then
-              return 0
-            fi
-            if [[ "$workflow" == "openclaw-performance.yml" && "$RELEASE_PROFILE" == "beta" ]]; then
-              echo "::warning::OpenClaw Performance ended with ${conclusion}; advisory for beta: ${url}"
-              return 0
-            fi
-            if [[ "$workflow" == "openclaw-release-checks.yml" ]]; then
-              jq '.jobs[] | select(.conclusion != "success" and .conclusion != "skipped") | {name, conclusion, url}' <<< "$run_json" || true
-              if [[ "$CHILD_WORKFLOW_REF" =~ ^tideclaw/alpha/[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{4}Z$ ]] && release_checks_advisory_only "$run_json"; then
-                echo "::warning::${workflow} ended with ${conclusion}, but Verify release checks accepted Tideclaw alpha advisory lanes."
-                return 0
-              fi
-            else
-              if [[ "$workflow" == "openclaw-performance.yml" ]]; then
-                echo "::error::OpenClaw Performance ended with ${conclusion}: ${url}"
-              fi
-              fetch_child_jobs | jq 'select(.conclusion != "success" and .conclusion != "skipped") | {name, conclusion, url: (.url // .html_url)}' || true
-            fi
-            exit 1
           }
 
           case "$CHILD_WORKFLOW_KIND" in
@@ -999,7 +816,7 @@ jobs:
               elif [[ "$TARGET_CONTEXT_REF" =~ ^(release/[0-9]{4}\.[0-9]+\.[0-9]+|extended-stable/[0-9]{4}\.[0-9]+\.33)$ ]]; then
                 args+=(-f target_context_ref="$TARGET_CONTEXT_REF")
               fi
-              dispatch_and_wait ci.yml "$dispatch_run_name" "${args[@]}"
+              dispatch_child ci.yml "$dispatch_run_name" "${args[@]}"
               ;;
             plugin-prerelease)
               plugin_prerelease_node_exclusions="$(
@@ -1018,7 +835,7 @@ jobs:
               if [[ -n "${CANDIDATE_ARTIFACT_JSON// }" ]]; then
                 args+=(-f candidate_artifact_json="$CANDIDATE_ARTIFACT_JSON")
               fi
-              dispatch_and_wait plugin-prerelease.yml "$dispatch_run_name" "${args[@]}"
+              dispatch_child plugin-prerelease.yml "$dispatch_run_name" "${args[@]}"
               ;;
             release-checks)
               {
@@ -1085,7 +902,7 @@ jobs:
               dispatch_id="full-release-validation-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-release-checks"
               dispatch_run_name="OpenClaw Release Checks ${dispatch_id}"
               args+=(-f dispatch_id="$dispatch_id")
-              dispatch_and_wait openclaw-release-checks.yml "$dispatch_run_name" "${args[@]}"
+              dispatch_child openclaw-release-checks.yml "$dispatch_run_name" "${args[@]}"
               ;;
             npm-telegram)
               args=(-f package_spec="$PACKAGE_SPEC" -f harness_ref="$TARGET_SHA" -f provider_mode="$PROVIDER_MODE")
@@ -1095,7 +912,7 @@ jobs:
               dispatch_id="full-release-validation-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-npm-telegram"
               dispatch_run_name="NPM Telegram Beta E2E ${dispatch_id}"
               args+=(-f dispatch_id="$dispatch_id")
-              dispatch_and_wait npm-telegram-beta-e2e.yml "$dispatch_run_name" "${args[@]}"
+              dispatch_child npm-telegram-beta-e2e.yml "$dispatch_run_name" "${args[@]}"
               ;;
             performance)
               fail_on_regression=true
@@ -1130,7 +947,7 @@ jobs:
                 -f publish_reports=false
                 -f dispatch_id="$dispatch_id"
               )
-              dispatch_and_wait openclaw-performance.yml "$dispatch_run_name" "${args[@]}"
+              dispatch_child openclaw-performance.yml "$dispatch_run_name" "${args[@]}"
               ;;
             *)
               echo "::error::Unsupported full-release child workflow kind ${CHILD_WORKFLOW_KIND}." >&2
@@ -1141,16 +958,15 @@ jobs:
   plugin_prerelease:
     name: Run plugin prerelease validation
     needs: [resolve_target, evidence_reuse, prepare_release_candidate]
-    if: ${{ always() && needs.resolve_target.result == 'success' && (needs.prepare_release_candidate.result == 'success' || needs.prepare_release_candidate.result == 'skipped') && contains(fromJSON('["all","plugin-prerelease"]'), inputs.rerun_group) && needs.evidence_reuse.outputs.reuse != 'true' }}
+    if: ${{ always() && github.run_attempt == 1 && needs.resolve_target.result == 'success' && (needs.prepare_release_candidate.result == 'success' || needs.prepare_release_candidate.result == 'skipped') && contains(fromJSON('["all","plugin-prerelease"]'), inputs.rerun_group) && needs.evidence_reuse.outputs.reuse != 'true' }}
     runs-on: ubuntu-24.04
-    # The child owns lane timeouts; this monitor also covers queue delay.
-    timeout-minutes: ${{ inputs.release_profile == 'full' && 300 || 240 }}
+    timeout-minutes: 15
     outputs:
       run_id: ${{ steps.dispatch.outputs.run_id }}
+      run_attempt: ${{ steps.dispatch.outputs.run_attempt }}
       url: ${{ steps.dispatch.outputs.url }}
-      conclusion: ${{ steps.dispatch.outputs.conclusion }}
     steps:
-      - name: Dispatch and monitor plugin prerelease
+      - name: Dispatch plugin prerelease
         id: dispatch
         env:
           GH_TOKEN: ${{ github.token }}
@@ -1161,23 +977,20 @@ jobs:
           PARENT_WORKFLOW_SHA: ${{ github.sha }}
           CANDIDATE_ARTIFACT_JSON: ${{ needs.prepare_release_candidate.outputs.candidate_artifact_json }}
           PLUGIN_PRERELEASE_NODE_EXCLUDE_PATTERNS_JSON: ${{ inputs.plugin_prerelease_node_exclude_patterns_json }}
-          FAIL_FAST: ${{ inputs.fail_fast }}
         run: *full_release_child_dispatch
 
   release_checks:
     name: Run release/live/Docker/QA validation
     needs: [resolve_target, evidence_reuse, prepare_release_candidate]
-    if: ${{ always() && needs.resolve_target.result == 'success' && (needs.prepare_release_candidate.result == 'success' || needs.prepare_release_candidate.result == 'skipped') && contains(fromJSON('["all","install-smoke","cross-os","live-e2e","package","qa-parity","qa-live"]'), inputs.rerun_group) && needs.evidence_reuse.outputs.reuse != 'true' }}
+    if: ${{ always() && github.run_attempt == 1 && needs.resolve_target.result == 'success' && (needs.prepare_release_candidate.result == 'success' || needs.prepare_release_candidate.result == 'skipped') && contains(fromJSON('["all","install-smoke","cross-os","live-e2e","package","qa-parity","qa-live"]'), inputs.rerun_group) && needs.evidence_reuse.outputs.reuse != 'true' }}
     runs-on: blacksmith-4vcpu-ubuntu-2404
-    # The bounded package critical path tops out at 310 minutes; 420 leaves
-    # queue/API margin. Parent timeout preserves the adopted child for exact cancellation.
-    timeout-minutes: 420
+    timeout-minutes: 15
     outputs:
       run_id: ${{ steps.dispatch.outputs.run_id }}
+      run_attempt: ${{ steps.dispatch.outputs.run_attempt }}
       url: ${{ steps.dispatch.outputs.url }}
-      conclusion: ${{ steps.dispatch.outputs.conclusion }}
     steps:
-      - name: Dispatch and monitor release checks
+      - name: Dispatch release checks
         id: dispatch
         env:
           GH_TOKEN: ${{ github.token }}
@@ -1206,17 +1019,16 @@ jobs:
   npm_telegram:
     name: Run package Telegram E2E
     needs: [resolve_target, evidence_reuse]
-    if: ${{ always() && needs.resolve_target.result == 'success' && contains(fromJSON('["all","npm-telegram"]'), inputs.rerun_group) && (inputs.npm_telegram_package_spec != '' || inputs.release_package_spec != '') && needs.evidence_reuse.outputs.reuse != 'true' }}
+    if: ${{ always() && github.run_attempt == 1 && needs.resolve_target.result == 'success' && contains(fromJSON('["all","npm-telegram"]'), inputs.rerun_group) && (inputs.npm_telegram_package_spec != '' || inputs.release_package_spec != '') && needs.evidence_reuse.outputs.reuse != 'true' }}
     continue-on-error: ${{ startsWith(github.ref, 'refs/heads/tideclaw/alpha/') }}
     runs-on: ubuntu-24.04
-    # The child owns lane timeouts; this monitor also covers queue delay.
-    timeout-minutes: ${{ inputs.release_profile == 'full' && 360 || 120 }}
+    timeout-minutes: 15
     outputs:
       run_id: ${{ steps.dispatch.outputs.run_id }}
+      run_attempt: ${{ steps.dispatch.outputs.run_attempt }}
       url: ${{ steps.dispatch.outputs.url }}
-      conclusion: ${{ steps.dispatch.outputs.conclusion }}
     steps:
-      - name: Dispatch and monitor npm Telegram E2E
+      - name: Dispatch npm Telegram E2E
         id: dispatch
         env:
           GH_TOKEN: ${{ github.token }}
@@ -1227,25 +1039,20 @@ jobs:
           PACKAGE_SPEC: ${{ inputs.npm_telegram_package_spec || inputs.release_package_spec }}
           PROVIDER_MODE: ${{ inputs.npm_telegram_provider_mode }}
           SCENARIO: ${{ inputs.npm_telegram_scenario }}
-          FAIL_FAST: ${{ inputs.fail_fast }}
         run: *full_release_child_dispatch
 
   performance:
     name: Run product performance evidence
     needs: [resolve_target, evidence_reuse]
-    if: ${{ always() && needs.resolve_target.result == 'success' && contains(fromJSON('["all","performance"]'), inputs.rerun_group) && needs.evidence_reuse.outputs.reuse != 'true' }}
-    # Keep this monitor off the four-slot GitHub-hosted pool so performance starts
-    # with the other child workflows instead of extending the critical path.
+    if: ${{ always() && github.run_attempt == 1 && needs.resolve_target.result == 'success' && contains(fromJSON('["all","performance"]'), inputs.rerun_group) && needs.evidence_reuse.outputs.reuse != 'true' }}
     runs-on: blacksmith-4vcpu-ubuntu-2404
-    # Artifact-only and publish paths top out at 255 and 280 minutes; 360 leaves
-    # queue/API margin. Parent timeout preserves the adopted child for exact cancellation.
-    timeout-minutes: 360
+    timeout-minutes: 15
     outputs:
       run_id: ${{ steps.dispatch.outputs.run_id }}
+      run_attempt: ${{ steps.dispatch.outputs.run_attempt }}
       url: ${{ steps.dispatch.outputs.url }}
-      conclusion: ${{ steps.dispatch.outputs.conclusion }}
     steps:
-      - name: Dispatch and monitor OpenClaw Performance
+      - name: Dispatch OpenClaw Performance
         id: dispatch
         env:
           GH_TOKEN: ${{ github.token }}
@@ -1255,8 +1062,9 @@ jobs:
           CHILD_WORKFLOW_REF: ${{ github.ref_name }}
           PARENT_WORKFLOW_SHA: ${{ github.sha }}
         run: *full_release_child_dispatch
-  summary:
-    name: Verify full validation
+
+  release_execution_plan:
+    name: Seal release execution plan
     needs:
       [
         resolve_target,
@@ -1270,442 +1078,365 @@ jobs:
         performance,
       ]
     if: always()
-    runs-on: ubuntu-24.04
-    timeout-minutes: 5
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
+    outputs:
+      sha256: ${{ steps.plan.outputs.sha256 }}
+      source_parent_attempt: ${{ steps.plan.outputs.source_parent_attempt }}
     steps:
-      - name: Verify child workflow results
+      - name: Checkout release execution plan tooling
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          ref: ${{ github.sha }}
+          sparse-checkout: |
+            scripts/full-release-validation-state.mjs
+            scripts/full-release-validation-policy.mjs
+            scripts/release-ci-summary.mjs
+            scripts/lib/plain-gh.mjs
+          sparse-checkout-cone-mode: false
+          persist-credentials: false
+
+      - name: Restore immutable release execution plan
+        if: ${{ github.run_attempt != 1 }}
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: full-release-execution-plan-${{ github.run_id }}
+          path: ${{ runner.temp }}/full-release-execution-plan
+
+      - name: Seal immutable release execution plan
+        id: plan
         env:
           GH_TOKEN: ${{ github.token }}
-          NORMAL_CI_RUN_ID: ${{ needs.normal_ci.outputs.run_id }}
-          PLUGIN_PRERELEASE_RUN_ID: ${{ needs.plugin_prerelease.outputs.run_id }}
-          RELEASE_CHECKS_RUN_ID: ${{ needs.release_checks.outputs.run_id }}
-          NPM_TELEGRAM_RUN_ID: ${{ needs.npm_telegram.outputs.run_id }}
-          PERFORMANCE_RUN_ID: ${{ needs.performance.outputs.run_id }}
-          NORMAL_CI_RESULT: ${{ needs.normal_ci.result }}
-          PLUGIN_PRERELEASE_RESULT: ${{ needs.plugin_prerelease.result }}
-          RELEASE_CHECKS_RESULT: ${{ needs.release_checks.result }}
-          NPM_TELEGRAM_RESULT: ${{ needs.npm_telegram.result }}
-          PERFORMANCE_RESULT: ${{ needs.performance.result }}
           RELEASE_PROFILE: ${{ inputs.release_profile }}
-          DOCKER_RUNTIME_ASSETS_PREFLIGHT_RESULT: ${{ needs.docker_runtime_assets_preflight.result }}
-          PREPARE_RELEASE_CANDIDATE_RESULT: ${{ needs.prepare_release_candidate.result }}
-          RELEASE_PACKAGE_SPEC: ${{ inputs.release_package_spec }}
-          NPM_TELEGRAM_PACKAGE_SPEC: ${{ inputs.npm_telegram_package_spec }}
-          PACKAGE_ACCEPTANCE_PACKAGE_SPEC: ${{ inputs.package_acceptance_package_spec }}
-          LIVE_SUITE_FILTER: ${{ needs.resolve_target.outputs.live_suite_filter }}
-          SKIP_PACKAGE_TELEGRAM_E2E: ${{ inputs.skip_package_telegram_e2e }}
+          RERUN_GROUP: ${{ inputs.rerun_group }}
+          TARGET_SHA: ${{ needs.resolve_target.outputs.sha }}
           EVIDENCE_REUSE: ${{ needs.evidence_reuse.outputs.reuse }}
+          EVIDENCE_RUN_ID: ${{ needs.evidence_reuse.outputs.evidence_run_id }}
           EVIDENCE_ROOT_RUN_ID: ${{ needs.evidence_reuse.outputs.evidence_root_run_id }}
           EVIDENCE_RUN_URL: ${{ needs.evidence_reuse.outputs.evidence_run_url }}
           EVIDENCE_SHA: ${{ needs.evidence_reuse.outputs.evidence_sha }}
           EVIDENCE_POLICY: ${{ needs.evidence_reuse.outputs.evidence_policy }}
-          EVIDENCE_MANIFEST: ${{ needs.evidence_reuse.outputs.evidence_manifest }}
-          RERUN_GROUP: ${{ inputs.rerun_group }}
-          TARGET_SHA: ${{ needs.resolve_target.outputs.sha }}
-          CHILD_WORKFLOW_REF: ${{ github.ref_name }}
-          PARENT_WORKFLOW_SHA: ${{ github.sha }}
+          EVIDENCE_CHANGED_PATHS: ${{ needs.evidence_reuse.outputs.changed_paths || '[]' }}
+          TRUSTED_WORKFLOW_JSON: ${{ needs.resolve_target.outputs.trusted_workflow_json }}
+          RELEASE_PACKAGE_SPEC: ${{ inputs.release_package_spec }}
+          PACKAGE_ACCEPTANCE_PACKAGE_SPEC: ${{ inputs.package_acceptance_package_spec }}
+          NPM_TELEGRAM_PACKAGE_SPEC: ${{ inputs.npm_telegram_package_spec }}
+          LIVE_SUITE_FILTER: ${{ needs.resolve_target.outputs.live_suite_filter }}
+          NORMAL_CI_RESULT: ${{ needs.normal_ci.result }}
+          NORMAL_CI_RUN_ID: ${{ needs.normal_ci.outputs.run_id }}
+          NORMAL_CI_RUN_ATTEMPT: ${{ needs.normal_ci.outputs.run_attempt }}
+          NORMAL_CI_URL: ${{ needs.normal_ci.outputs.url }}
+          PLUGIN_PRERELEASE_RESULT: ${{ needs.plugin_prerelease.result }}
+          PLUGIN_PRERELEASE_RUN_ID: ${{ needs.plugin_prerelease.outputs.run_id }}
+          PLUGIN_PRERELEASE_RUN_ATTEMPT: ${{ needs.plugin_prerelease.outputs.run_attempt }}
+          PLUGIN_PRERELEASE_URL: ${{ needs.plugin_prerelease.outputs.url }}
+          RELEASE_CHECKS_RESULT: ${{ needs.release_checks.result }}
+          RELEASE_CHECKS_RUN_ID: ${{ needs.release_checks.outputs.run_id }}
+          RELEASE_CHECKS_RUN_ATTEMPT: ${{ needs.release_checks.outputs.run_attempt }}
+          RELEASE_CHECKS_URL: ${{ needs.release_checks.outputs.url }}
+          NPM_TELEGRAM_RESULT: ${{ needs.npm_telegram.result }}
+          NPM_TELEGRAM_RUN_ID: ${{ needs.npm_telegram.outputs.run_id }}
+          NPM_TELEGRAM_RUN_ATTEMPT: ${{ needs.npm_telegram.outputs.run_attempt }}
+          NPM_TELEGRAM_URL: ${{ needs.npm_telegram.outputs.url }}
+          PERFORMANCE_RESULT: ${{ needs.performance.result }}
+          PERFORMANCE_RUN_ID: ${{ needs.performance.outputs.run_id }}
+          PERFORMANCE_RUN_ATTEMPT: ${{ needs.performance.outputs.run_attempt }}
+          PERFORMANCE_URL: ${{ needs.performance.outputs.url }}
+          RESOLVE_TARGET_RESULT: ${{ needs.resolve_target.result }}
+          DOCKER_RUNTIME_ASSETS_PREFLIGHT_RESULT: ${{ needs.docker_runtime_assets_preflight.result }}
+          PREPARE_RELEASE_CANDIDATE_RESULT: ${{ needs.prepare_release_candidate.result }}
+          FULL_RELEASE_RESTORE_PLAN: ${{ github.run_attempt != 1 }}
+          FULL_RELEASE_EXECUTION_PLAN_PATH: ${{ runner.temp }}/full-release-execution-plan/full-release-execution-plan.json
         run: |
           set -euo pipefail
-
-          gh_with_retry() {
-            local output status attempt
-            for attempt in 1 2 3 4 5 6; do
-              set +e
-              output="$(gh "$@" 2>&1)"
-              status=$?
-              set -e
-              if [[ "$status" -eq 0 ]]; then
-                printf '%s\n' "$output"
-                return 0
-              fi
-              if [[ "$output" == *"Bad credentials"* || "$output" == *"HTTP 401"* || "$output" == *"secondary rate limit"* || "$output" == *"API rate limit"* || "$output" == *"HTTP 429"* || "$output" == *"abuse detection"* || "$output" == *"Sorry. Your account was suspended"* || "$output" =~ $GH_TRANSIENT_SERVER_OR_NETWORK_PATTERN ]]; then
-                echo "::warning::gh $* failed on attempt ${attempt}: ${output}" >&2
-                sleep $((attempt * 10))
-                continue
-              fi
-              printf '%s\n' "$output" >&2
-              return "$status"
-            done
-            printf '%s\n' "$output" >&2
-            return "$status"
-          }
-
-          release_check_blocking_job() {
-            case "$1" in
-              "resolve_target" | \
-              "Prepare release package artifact" | \
-              "install_smoke_release_checks / "* | \
-              "Run package acceptance" | \
-              "Run package acceptance / "*)
-                return 0
-                ;;
-            esac
-            return 1
-          }
-
-          release_checks_advisory_only() {
-            local run_json="$1"
-            local verifier_conclusion name saw_advisory failed
-
-            verifier_conclusion="$(
-              jq -r '.jobs[] | select(.name == "Verify release checks") | .conclusion' <<< "$run_json" |
-                tail -n 1
+          if [[ "$FULL_RELEASE_RESTORE_PLAN" != "true" ]]; then
+            export FULL_RELEASE_PLAN_INPUTS_JSON="$(
+            jq -cn \
+              --arg parentRunId "$GITHUB_RUN_ID" \
+              --arg parentRunAttempt "$GITHUB_RUN_ATTEMPT" \
+              --arg workflowRef "$GITHUB_REF_NAME" \
+              --arg workflowSha "$GITHUB_SHA" \
+              --argjson trustedWorkflow "$TRUSTED_WORKFLOW_JSON" \
+              --arg evidenceReuse "$EVIDENCE_REUSE" \
+              --arg evidenceRunId "$EVIDENCE_RUN_ID" \
+              --arg evidenceRootRunId "$EVIDENCE_ROOT_RUN_ID" \
+              --arg evidenceRunUrl "$EVIDENCE_RUN_URL" \
+              --arg evidenceSha "$EVIDENCE_SHA" \
+              --arg evidencePolicy "$EVIDENCE_POLICY" \
+              --argjson evidenceChangedPaths "$EVIDENCE_CHANGED_PATHS" \
+              --arg rerunGroup "$RERUN_GROUP" \
+              --arg releasePackageSpec "$RELEASE_PACKAGE_SPEC" \
+              --arg packageAcceptancePackageSpec "$PACKAGE_ACCEPTANCE_PACKAGE_SPEC" \
+              --arg npmTelegramPackageSpec "$NPM_TELEGRAM_PACKAGE_SPEC" \
+              --arg liveSuiteFilter "$LIVE_SUITE_FILTER" \
+              --arg resolveTargetResult "$RESOLVE_TARGET_RESULT" \
+              --arg dockerPreflightResult "$DOCKER_RUNTIME_ASSETS_PREFLIGHT_RESULT" \
+              --arg prepareCandidateResult "$PREPARE_RELEASE_CANDIDATE_RESULT" \
+              --arg normalCiResult "$NORMAL_CI_RESULT" \
+              --arg normalCiRunId "$NORMAL_CI_RUN_ID" \
+              --arg normalCiRunAttempt "$NORMAL_CI_RUN_ATTEMPT" \
+              --arg normalCiUrl "$NORMAL_CI_URL" \
+              --arg pluginPrereleaseResult "$PLUGIN_PRERELEASE_RESULT" \
+              --arg pluginPrereleaseRunId "$PLUGIN_PRERELEASE_RUN_ID" \
+              --arg pluginPrereleaseRunAttempt "$PLUGIN_PRERELEASE_RUN_ATTEMPT" \
+              --arg pluginPrereleaseUrl "$PLUGIN_PRERELEASE_URL" \
+              --arg releaseChecksResult "$RELEASE_CHECKS_RESULT" \
+              --arg releaseChecksRunId "$RELEASE_CHECKS_RUN_ID" \
+              --arg releaseChecksRunAttempt "$RELEASE_CHECKS_RUN_ATTEMPT" \
+              --arg releaseChecksUrl "$RELEASE_CHECKS_URL" \
+              --arg npmTelegramResult "$NPM_TELEGRAM_RESULT" \
+              --arg npmTelegramRunId "$NPM_TELEGRAM_RUN_ID" \
+              --arg npmTelegramRunAttempt "$NPM_TELEGRAM_RUN_ATTEMPT" \
+              --arg npmTelegramUrl "$NPM_TELEGRAM_URL" \
+              --arg performanceResult "$PERFORMANCE_RESULT" \
+              --arg performanceRunId "$PERFORMANCE_RUN_ID" \
+              --arg performanceRunAttempt "$PERFORMANCE_RUN_ATTEMPT" \
+              --arg performanceUrl "$PERFORMANCE_URL" \
+              '{
+                parentRunId: $parentRunId,
+                parentRunAttempt: $parentRunAttempt,
+                workflowRef: $workflowRef,
+                workflowSha: $workflowSha,
+                trustedWorkflow: $trustedWorkflow,
+                evidenceReuse: $evidenceReuse,
+                evidenceRunId: $evidenceRunId,
+                evidenceRootRunId: $evidenceRootRunId,
+                evidenceRunUrl: $evidenceRunUrl,
+                evidenceSha: $evidenceSha,
+                evidencePolicy: $evidencePolicy,
+                evidenceChangedPaths: $evidenceChangedPaths,
+                rerunGroup: $rerunGroup,
+                releasePackageSpec: $releasePackageSpec,
+                packageAcceptancePackageSpec: $packageAcceptancePackageSpec,
+                npmTelegramPackageSpec: $npmTelegramPackageSpec,
+                liveSuiteFilter: $liveSuiteFilter,
+                resolveTargetResult: $resolveTargetResult,
+                dockerPreflightResult: $dockerPreflightResult,
+                prepareCandidateResult: $prepareCandidateResult,
+                children: {
+                  normalCi: {result: $normalCiResult, runId: $normalCiRunId, runAttempt: $normalCiRunAttempt, url: $normalCiUrl},
+                  pluginPrerelease: {result: $pluginPrereleaseResult, runId: $pluginPrereleaseRunId, runAttempt: $pluginPrereleaseRunAttempt, url: $pluginPrereleaseUrl},
+                  releaseChecks: {result: $releaseChecksResult, runId: $releaseChecksRunId, runAttempt: $releaseChecksRunAttempt, url: $releaseChecksUrl},
+                  npmTelegram: {result: $npmTelegramResult, runId: $npmTelegramRunId, runAttempt: $npmTelegramRunAttempt, url: $npmTelegramUrl},
+                  productPerformance: {result: $performanceResult, runId: $performanceRunId, runAttempt: $performanceRunAttempt, url: $performanceUrl}
+                }
+              }'
             )"
-            if [[ "$verifier_conclusion" != "success" ]]; then
-              return 1
-            fi
-
-            saw_advisory=0
-            failed=0
-            while IFS= read -r name; do
-              [[ -z "${name// }" ]] && continue
-              if release_check_blocking_job "$name"; then
-                echo "::error::${name} is a package-safety Tideclaw alpha release-check lane."
-                failed=1
-              else
-                saw_advisory=1
-              fi
-            done < <(jq -r '.jobs[] | select(.conclusion != "success" and .conclusion != "skipped") | .name' <<< "$run_json")
-
-            [[ "$saw_advisory" == "1" && "$failed" == "0" ]]
-          }
-
-          check_child() {
-            local label="$1"
-            local run_id="$2"
-            local required="$3"
-            local advisory_ok="${4:-0}"
-
-            if [[ -z "${run_id// }" ]]; then
-              if [[ "$required" == "0" ]]; then
-                echo "${label}: skipped"
-                return 0
-              fi
-              echo "::error::${label} did not record a child run id."
-              return 1
-            fi
-
-            local run_json status conclusion url attempt head_sha
-            run_json="$(gh_with_retry run view "$run_id" --json status,conclusion,url,attempt,headSha,jobs)"
-            status="$(jq -r '.status' <<< "$run_json")"
-            conclusion="$(jq -r '.conclusion' <<< "$run_json")"
-            url="$(jq -r '.url' <<< "$run_json")"
-            attempt="$(jq -r '.attempt' <<< "$run_json")"
-            head_sha="$(jq -r '.headSha // ""' <<< "$run_json")"
-            echo "${label}: ${status}/${conclusion} attempt ${attempt} head ${head_sha}: ${url}"
-
-            if [[ "$head_sha" != "$PARENT_WORKFLOW_SHA" ]]; then
-              echo "::error::${label} child run used workflow SHA ${head_sha}, expected parent workflow SHA ${PARENT_WORKFLOW_SHA}. Use the SHA-pinned release helper when a moving branch cannot stay fixed."
-              return 1
-            fi
-
-            if [[ "$status" != "completed" || "$conclusion" != "success" ]]; then
-              if [[ "$advisory_ok" == "1" && "$label" == "product_performance" && "$status" == "completed" ]]; then
-                echo "::warning::${label} ended with ${conclusion}; advisory for beta: ${url}"
-                return 0
-              fi
-              if [[ "$advisory_ok" == "1" && "$label" == "release_checks" ]]; then
-                if release_checks_advisory_only "$run_json"; then
-                  echo "::warning::${label} child run ended with ${status}/${conclusion}, but Verify release checks accepted Tideclaw alpha advisory lanes: ${url}"
-                  return 0
-                fi
-              fi
-              echo "::error::${label} child run ended with ${status}/${conclusion}: ${url}"
-              jq '.jobs[] | select(.conclusion != "success" and .conclusion != "skipped") | {name, status, conclusion, url}' <<< "$run_json" || true
-              return 1
-            fi
-          }
-
-          append_child_overview() {
-            {
-              echo
-              echo "### Child workflow overview"
-              echo
-              echo "| Child | Result | Minutes | Head SHA | Run |"
-              echo "| --- | --- | ---: | --- | --- |"
-              echo "| \`docker_runtime_assets_preflight\` | \`${DOCKER_RUNTIME_ASSETS_PREFLIGHT_RESULT}\` |  | current workflow |  |"
-            } >> "$GITHUB_STEP_SUMMARY"
-
-            append_child_row() {
-              local label="$1"
-              local run_id="$2"
-              local result="$3"
-
-              if [[ -z "${run_id// }" ]]; then
-                echo "| \`${label}\` | \`${result}\` |  | skipped |" >> "$GITHUB_STEP_SUMMARY"
-                return 0
-              fi
-
-              local run_json row
-              run_json="$(gh_with_retry run view "$run_id" --json status,conclusion,url,createdAt,updatedAt,headSha)"
-              row="$(
-                jq -r --arg label "$label" '
-                  def ts: fromdateiso8601;
-                  . as $run |
-                  ($run.createdAt // "") as $created |
-                  ($run.updatedAt // "") as $updated |
-                  (if ($created | length) > 0 and ($updated | length) > 0
-                    then (((($updated | ts) - ($created | ts)) / 60) * 10 | round / 10 | tostring)
-                    else ""
-                  end) as $minutes |
-                  ($run.headSha // "") as $head |
-                  "| `" + $label + "` | `" + ($run.status // "") + "/" + ($run.conclusion // "") + "` | " + $minutes + " | `" + $head + "` | [run](" + ($run.url // "") + ") |"
-                ' <<< "$run_json"
-              )"
-              echo "$row" >> "$GITHUB_STEP_SUMMARY"
-            }
-
-            append_child_row "normal_ci" "$NORMAL_CI_RUN_ID" "$NORMAL_CI_RESULT"
-            append_child_row "plugin_prerelease" "$PLUGIN_PRERELEASE_RUN_ID" "$PLUGIN_PRERELEASE_RESULT"
-            append_child_row "release_checks" "$RELEASE_CHECKS_RUN_ID" "$RELEASE_CHECKS_RESULT"
-            append_child_row "npm_telegram" "$NPM_TELEGRAM_RUN_ID" "$NPM_TELEGRAM_RESULT"
-            append_child_row "product_performance" "$PERFORMANCE_RUN_ID" "$PERFORMANCE_RESULT"
-          }
-
-          summarize_child_timing() {
-            local label="$1"
-            local run_id="$2"
-            if [[ -z "${run_id// }" ]]; then
-              return 0
-            fi
-
-            {
-              echo
-              echo "### Slowest jobs: ${label}"
-              echo
-              gh_with_retry run view "$run_id" --json jobs --jq '
-                def ts: fromdateiso8601;
-                "| Job | Result | Minutes |",
-                "| --- | --- | ---: |",
-                ([.jobs[]
-                  | select(.startedAt != "0001-01-01T00:00:00Z" and .completedAt != "0001-01-01T00:00:00Z")
-                  | . + {durationMin: ((((.completedAt | ts) - (.startedAt | ts)) / 60) * 10 | round / 10)}
-                  | {name, conclusion, durationMin}]
-                  | sort_by(.durationMin)
-                  | reverse
-                  | .[0:10]
-                  | map("| `" + (.name | gsub("\\|"; "\\|")) + "` | `" + ((.conclusion // "") | tostring) + "` | " + (.durationMin | tostring) + " |")
-                  | .[])
-              ' || echo "_Unable to summarize jobs for run ${run_id}._"
-              echo
-              echo "### Longest start delays: ${label}"
-              echo
-              gh_with_retry api --paginate "repos/${GITHUB_REPOSITORY}/actions/runs/${run_id}/jobs?per_page=100" --jq ".jobs[] | @json" | jq -sr '
-                def ts: fromdateiso8601;
-                "| Job | Result | Start delay minutes | Run minutes |",
-                "| --- | --- | ---: | ---: |",
-                ([.[]
-                  | select(.created_at != null and .started_at != null)
-                  | . + {
-                      startDelayMin: ((((.started_at | ts) - (.created_at | ts)) / 60) * 10 | round / 10),
-                      durationMin: (if .completed_at == null then null else ((((.completed_at | ts) - (.started_at | ts)) / 60) * 10 | round / 10) end)
-                    }
-                  | select(.startDelayMin > 0)
-                  | {name, conclusion, startDelayMin, durationMin}]
-                  | sort_by(.startDelayMin)
-                  | reverse
-                  | .[0:10]
-                  | map("| `" + (.name | gsub("\\|"; "\\|")) + "` | `" + ((.conclusion // "") | tostring) + "` | " + (.startDelayMin | tostring) + " | " + ((.durationMin // "") | tostring) + " |")
-                  | .[])
-              ' || echo "_Unable to summarize start delays for run ${run_id}._"
-            } >> "$GITHUB_STEP_SUMMARY"
-          }
-
-          summarize_failed_child() {
-            local label="$1"
-            local run_id="$2"
-            if [[ -z "${run_id// }" ]]; then
-              return 0
-            fi
-
-            local run_json status conclusion artifacts_json
-            run_json="$(gh_with_retry run view "$run_id" --json status,conclusion,url,jobs)"
-            status="$(jq -r '.status' <<< "$run_json")"
-            conclusion="$(jq -r '.conclusion' <<< "$run_json")"
-            if [[ "$status" == "completed" && "$conclusion" == "success" ]]; then
-              return 0
-            fi
-
-            {
-              echo
-              echo "### Failed child detail: ${label}"
-              echo
-              jq -r '
-                "- Run: " + (.url // ""),
-                "- Result: `" + (.status // "") + "/" + (.conclusion // "") + "`",
-                "",
-                "Failed jobs:",
-                (.jobs[]
-                  | select(.conclusion != "success" and .conclusion != "skipped")
-                  | "- `" + (.name | gsub("`"; "\\`")) + "`: `" + ((.conclusion // .status // "") | tostring) + "` " + (.url // ""))
-              ' <<< "$run_json" || true
-              echo
-              echo "Artifacts:"
-              artifacts_json="$(
-                gh_with_retry api "repos/${GITHUB_REPOSITORY}/actions/runs/${run_id}/artifacts?per_page=100" 2>/dev/null || true
-              )"
-              if [[ -n "${artifacts_json// }" ]]; then
-                jq -r '
-                  if ((.artifacts // []) | length) == 0 then
-                    "- none"
-                  else
-                    (.artifacts[]
-                      | "- `" + (.name | gsub("`"; "\\`")) + "` (" + ((.size_in_bytes // 0) | tostring) + " bytes)")
-                  end
-                ' <<< "$artifacts_json" || echo "- unable to list artifacts"
-              else
-                echo "- unable to list artifacts"
-              fi
-            } >> "$GITHUB_STEP_SUMMARY"
-          }
-
-          failed=0
-          normal_ci_required=0
-          plugin_prerelease_required=0
-          release_checks_required=0
-          npm_telegram_required=0
-          performance_required=0
-          candidate_required=0
-          if [[ "$RERUN_GROUP" == "npm-telegram" || ( "$RERUN_GROUP" == "all" && ( -n "${NPM_TELEGRAM_PACKAGE_SPEC// }" || -n "${RELEASE_PACKAGE_SPEC// }" ) ) ]]; then
-            npm_telegram_required=1
-          fi
-          echo "- Package Telegram E2E deferred: \`${SKIP_PACKAGE_TELEGRAM_E2E}\`" >> "$GITHUB_STEP_SUMMARY"
-          if [[ -z "${RELEASE_PACKAGE_SPEC// }" && -z "${PACKAGE_ACCEPTANCE_PACKAGE_SPEC// }" ]]; then
-            case "$RERUN_GROUP" in
-              all|plugin-prerelease|cross-os|package)
-                candidate_required=1
-                ;;
-              live-e2e)
-                [[ -n "${LIVE_SUITE_FILTER// }" ]] || candidate_required=1
-                ;;
-            esac
-          fi
-          if [[ "$candidate_required" == "1" && "$EVIDENCE_REUSE" != "true" && "$PREPARE_RELEASE_CANDIDATE_RESULT" != "success" ]]; then
-            echo "::error::Shared release candidate preparation ended with ${PREPARE_RELEASE_CANDIDATE_RESULT}."
-            failed=1
-          fi
-          if [[ "$RERUN_GROUP" == "all" && "$EVIDENCE_REUSE" == "true" ]]; then
-            # Lanes were skipped because a prior green validation covers this
-            # target; re-verify the chain-root run and its recorded child runs
-            # so evidence that went stale after resolution cannot pass.
-            reused_npm_telegram_run_id="$(jq -r '.childRuns.npmTelegram // ""' <<< "$EVIDENCE_MANIFEST")"
-            if [[ "$npm_telegram_required" == "1" && -z "${reused_npm_telegram_run_id// }" ]]; then
-              echo "::error::Reused evidence did not record the required npm Telegram child run."
-              failed=1
-            fi
-            evidence_state="$(gh_with_retry run view "$EVIDENCE_ROOT_RUN_ID" --json status,conclusion --jq '(.status // "") + "/" + (.conclusion // "")')"
-            if [[ "$evidence_state" != "completed/success" ]]; then
-              echo "::error::Reused evidence run ${EVIDENCE_ROOT_RUN_ID} is ${evidence_state}; evidence is no longer valid."
-              failed=1
-            fi
-            while IFS= read -r evidence_child_run_id; do
-              [[ -n "$evidence_child_run_id" ]] || continue
-              evidence_child_state="$(gh_with_retry run view "$evidence_child_run_id" --json status,conclusion --jq '(.status // "") + "/" + (.conclusion // "")')"
-              if [[ "$evidence_child_state" != "completed/success" ]]; then
-                echo "::error::Reused evidence child run ${evidence_child_run_id} is ${evidence_child_state}; evidence is no longer valid."
-                failed=1
-              fi
-            done < <(jq -r '[.childRuns.normalCi // "", .childRuns.pluginPrerelease // "", .childRuns.releaseChecks // "", .childRuns.npmTelegram // "", (.childRuns.productPerformance.runId // "")] | map(select(. != "")) | .[]' <<< "$EVIDENCE_MANIFEST")
-            if [[ "$failed" == "0" ]]; then
-              emit_reused_child_dispatch() {
-                local workflow="$1"
-                local run_id="$2"
-                if [[ -n "${run_id// }" ]]; then
-                  echo "Dispatched ${workflow}: https://github.com/${GITHUB_REPOSITORY}/actions/runs/${run_id}"
-                fi
-              }
-              emit_reused_child_dispatch "ci.yml" "$(jq -r '.childRuns.normalCi // ""' <<< "$EVIDENCE_MANIFEST")"
-              emit_reused_child_dispatch "plugin-prerelease.yml" "$(jq -r '.childRuns.pluginPrerelease // ""' <<< "$EVIDENCE_MANIFEST")"
-              emit_reused_child_dispatch "openclaw-release-checks.yml" "$(jq -r '.childRuns.releaseChecks // ""' <<< "$EVIDENCE_MANIFEST")"
-              emit_reused_child_dispatch "npm-telegram-beta-e2e.yml" "$(jq -r '.childRuns.npmTelegram // ""' <<< "$EVIDENCE_MANIFEST")"
-              emit_reused_child_dispatch "openclaw-performance.yml" "$(jq -r '.childRuns.productPerformance.runId // ""' <<< "$EVIDENCE_MANIFEST")"
-              {
-                echo "### Reused validation evidence"
-                echo
-                echo "- Evidence run: ${EVIDENCE_RUN_URL}"
-                echo "- Evidence SHA: \`${EVIDENCE_SHA}\`"
-                echo "- Target SHA: \`${TARGET_SHA}\`"
-                echo "- Reuse policy: \`${EVIDENCE_POLICY}\`"
-              } >> "$GITHUB_STEP_SUMMARY"
-            fi
-          elif [[ "$RERUN_GROUP" == "all" && "$DOCKER_RUNTIME_ASSETS_PREFLIGHT_RESULT" != "success" ]]; then
-            echo "::error::Docker runtime-assets preflight ended with ${DOCKER_RUNTIME_ASSETS_PREFLIGHT_RESULT}."
-            failed=1
-          elif [[ "$RERUN_GROUP" == "all" ]]; then
-            normal_ci_required=1
-            plugin_prerelease_required=1
-            release_checks_required=1
-            performance_required=1
-          else
-            case "$RERUN_GROUP" in
-              ci)
-                normal_ci_required=1
-                ;;
-              plugin-prerelease)
-                plugin_prerelease_required=1
-                ;;
-              install-smoke|cross-os|live-e2e|package|qa-parity|qa-live)
-                release_checks_required=1
-                ;;
-              performance)
-                performance_required=1
-                ;;
-            esac
           fi
+          node scripts/full-release-validation-state.mjs plan
 
-          append_child_overview
+      - name: Upload immutable release execution plan
+        if: ${{ always() && github.run_attempt == 1 }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: full-release-execution-plan-${{ github.run_id }}
+          path: ${{ runner.temp }}/full-release-execution-plan
+          if-no-files-found: error
 
-          if [[ "$NORMAL_CI_RESULT" == "skipped" && -z "${NORMAL_CI_RUN_ID// }" ]]; then
-            check_child "normal_ci" "" "$normal_ci_required" || failed=1
-          else
-            check_child "normal_ci" "$NORMAL_CI_RUN_ID" 1 || failed=1
+  release_decision:
+    name: Release Decision
+    needs: [resolve_target, release_execution_plan]
+    if: always()
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 720
+    outputs:
+      state: ${{ steps.state.outputs.state }}
+    steps:
+      - name: Checkout release decision tooling
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          ref: ${{ github.sha }}
+          sparse-checkout: |
+            scripts/full-release-validation-state.mjs
+            scripts/full-release-validation-policy.mjs
+          sparse-checkout-cone-mode: false
+          persist-credentials: false
+
+      - name: Download immutable release execution plan
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: full-release-execution-plan-${{ github.run_id }}
+          path: ${{ runner.temp }}/full-release-execution-plan
+
+      - name: Evaluate release decision
+        id: state
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+          FAIL_FAST: ${{ inputs.fail_fast }}
+          RELEASE_PROFILE: ${{ inputs.release_profile }}
+          RERUN_GROUP: ${{ inputs.rerun_group }}
+          TARGET_SHA: ${{ needs.resolve_target.outputs.sha }}
+          FULL_RELEASE_STATE_MODE: decision
+          FULL_RELEASE_EXECUTION_PLAN_PATH: ${{ runner.temp }}/full-release-execution-plan/full-release-execution-plan.json
+          FULL_RELEASE_STATE_PATH: ${{ runner.temp }}/full-release-decision/full-release-decision.json
+        run: &full_release_state |
+          set -euo pipefail
+          node scripts/full-release-validation-state.mjs "$FULL_RELEASE_STATE_MODE"
+
+      - name: Upload release decision
+        if: always() && steps.state.outputs.state != ''
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: full-release-decision-${{ github.run_id }}-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/full-release-decision
+          if-no-files-found: error
+
+      - name: Enforce release decision
+        if: always()
+        env:
+          RELEASE_DECISION_STATE: ${{ steps.state.outputs.state }}
+        run: |
+          set -euo pipefail
+          if [[ "$RELEASE_DECISION_STATE" == "passed" ]]; then
+            exit 0
           fi
+          echo "::error::Release Decision ended in ${RELEASE_DECISION_STATE:-orchestration_error}."
+          exit 1
 
-          if [[ "$PLUGIN_PRERELEASE_RESULT" == "skipped" && -z "${PLUGIN_PRERELEASE_RUN_ID// }" ]]; then
-            check_child "plugin_prerelease" "" "$plugin_prerelease_required" || failed=1
-          else
-            check_child "plugin_prerelease" "$PLUGIN_PRERELEASE_RUN_ID" 1 || failed=1
-          fi
+  diagnostic_drain:
+    name: Diagnostic Drain
+    needs: [resolve_target, release_execution_plan]
+    if: always()
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 720
+    outputs:
+      state: ${{ steps.state.outputs.state }}
+      normal_ci_conclusion: ${{ steps.state.outputs.normalCi_conclusion }}
+      plugin_prerelease_conclusion: ${{ steps.state.outputs.pluginPrerelease_conclusion }}
+      release_checks_conclusion: ${{ steps.state.outputs.releaseChecks_conclusion }}
+      npm_telegram_conclusion: ${{ steps.state.outputs.npmTelegram_conclusion }}
+      performance_conclusion: ${{ steps.state.outputs.productPerformance_conclusion }}
+    steps:
+      - name: Checkout diagnostic drain tooling
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          ref: ${{ github.sha }}
+          sparse-checkout: |
+            scripts/full-release-validation-state.mjs
+            scripts/full-release-validation-policy.mjs
+            scripts/release-ci-summary.mjs
+            scripts/lib/plain-gh.mjs
+          sparse-checkout-cone-mode: false
+          persist-credentials: false
 
-          if [[ "$RELEASE_CHECKS_RESULT" == "skipped" && -z "${RELEASE_CHECKS_RUN_ID// }" ]]; then
-            check_child "release_checks" "" "$release_checks_required" || failed=1
-          elif [[ "$CHILD_WORKFLOW_REF" =~ ^tideclaw/alpha/[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{4}Z$ ]]; then
-            check_child "release_checks" "$RELEASE_CHECKS_RUN_ID" 1 1 || failed=1
-          else
-            check_child "release_checks" "$RELEASE_CHECKS_RUN_ID" 1 || failed=1
-          fi
+      - name: Download immutable release execution plan
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: full-release-execution-plan-${{ github.run_id }}
+          path: ${{ runner.temp }}/full-release-execution-plan
 
-          if [[ "$NPM_TELEGRAM_RESULT" == "skipped" && -z "${NPM_TELEGRAM_RUN_ID// }" ]]; then
-            check_child "npm_telegram" "" "$npm_telegram_required" || failed=1
-          elif [[ "$CHILD_WORKFLOW_REF" =~ ^tideclaw/alpha/[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{4}Z$ ]]; then
-            check_child "npm_telegram" "$NPM_TELEGRAM_RUN_ID" 0 || echo "::warning::npm_telegram is advisory for Tideclaw alpha validation."
-          else
-            check_child "npm_telegram" "$NPM_TELEGRAM_RUN_ID" 1 || failed=1
-          fi
+      - name: Drain child diagnostics
+        id: state
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+          FAIL_FAST: "false"
+          RELEASE_PROFILE: ${{ inputs.release_profile }}
+          RERUN_GROUP: ${{ inputs.rerun_group }}
+          TARGET_SHA: ${{ needs.resolve_target.outputs.sha }}
+          FULL_RELEASE_STATE_MODE: drain
+          FULL_RELEASE_EXECUTION_PLAN_PATH: ${{ runner.temp }}/full-release-execution-plan/full-release-execution-plan.json
+          FULL_RELEASE_STATE_PATH: ${{ runner.temp }}/full-release-diagnostics/full-release-diagnostic-manifest.json
+        run: *full_release_state
 
-          if [[ "$PERFORMANCE_RESULT" == "skipped" && -z "${PERFORMANCE_RUN_ID// }" ]]; then
-            check_child "product_performance" "" "$performance_required" || failed=1
-          else
-            performance_advisory=0
-            [[ "$RELEASE_PROFILE" == "beta" ]] && performance_advisory=1
-            check_child "product_performance" "$PERFORMANCE_RUN_ID" "$performance_required" "$performance_advisory" || failed=1
-          fi
+      - name: Upload diagnostic drain manifest
+        if: always() && steps.state.outputs.state != ''
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: full-release-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/full-release-diagnostics
+          if-no-files-found: error
 
-          summarize_child_timing "normal_ci" "$NORMAL_CI_RUN_ID"
-          summarize_child_timing "plugin_prerelease" "$PLUGIN_PRERELEASE_RUN_ID"
-          summarize_child_timing "release_checks" "$RELEASE_CHECKS_RUN_ID"
-          summarize_child_timing "npm_telegram" "$NPM_TELEGRAM_RUN_ID"
-          summarize_child_timing "product_performance" "$PERFORMANCE_RUN_ID"
+      - name: Enforce diagnostic drain integrity
+        if: always()
+        env:
+          DIAGNOSTIC_DRAIN_STATE: ${{ steps.state.outputs.state }}
+        run: |
+          set -euo pipefail
+          case "$DIAGNOSTIC_DRAIN_STATE" in
+            passed|blocked_complete)
+              exit 0
+              ;;
+            *)
+              echo "::error::Diagnostic Drain ended in ${DIAGNOSTIC_DRAIN_STATE:-orchestration_error}."
+              exit 1
+              ;;
+          esac
 
-          if [[ "$failed" != "0" ]]; then
-            summarize_failed_child "normal_ci" "$NORMAL_CI_RUN_ID"
-            summarize_failed_child "plugin_prerelease" "$PLUGIN_PRERELEASE_RUN_ID"
-            summarize_failed_child "release_checks" "$RELEASE_CHECKS_RUN_ID"
-            summarize_failed_child "npm_telegram" "$NPM_TELEGRAM_RUN_ID"
-            summarize_failed_child "product_performance" "$PERFORMANCE_RUN_ID"
-          fi
+  summary:
+    name: Verify full validation
+    needs:
+      [
+        resolve_target,
+        evidence_reuse,
+        docker_runtime_assets_preflight,
+        prepare_release_candidate,
+        normal_ci,
+        plugin_prerelease,
+        release_checks,
+        npm_telegram,
+        performance,
+        release_execution_plan,
+        release_decision,
+        diagnostic_drain,
+      ]
+    if: always()
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - name: Checkout release state verifier
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          ref: ${{ github.sha }}
+          sparse-checkout: |
+            scripts/full-release-validation-state.mjs
+            scripts/full-release-validation-policy.mjs
+            scripts/release-ci-summary.mjs
+            scripts/lib/plain-gh.mjs
+          sparse-checkout-cone-mode: false
+          persist-credentials: false
 
-          exit "$failed"
+      - name: Download immutable release execution plan
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: full-release-execution-plan-${{ github.run_id }}
+          path: ${{ runner.temp }}/full-release-execution-plan
+
+      - name: Download release decision attempts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          pattern: full-release-decision-${{ github.run_id }}-*
+          path: ${{ runner.temp }}/full-release-decision-attempts
+
+      - name: Download diagnostic drain attempts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          pattern: full-release-diagnostics-${{ github.run_id }}-*
+          path: ${{ runner.temp }}/full-release-diagnostic-attempts
+
+      - name: Select newest compatible release state artifacts
+        id: selected_state
+        env:
+          RELEASE_PROFILE: ${{ inputs.release_profile }}
+          RERUN_GROUP: ${{ inputs.rerun_group }}
+          TARGET_SHA: ${{ needs.resolve_target.outputs.sha }}
+          RELEASE_EXECUTION_PLAN_PATH: ${{ runner.temp }}/full-release-execution-plan/full-release-execution-plan.json
+          RELEASE_DECISION_ATTEMPTS_PATH: ${{ runner.temp }}/full-release-decision-attempts
+          DIAGNOSTIC_DRAIN_ATTEMPTS_PATH: ${{ runner.temp }}/full-release-diagnostic-attempts
+          RELEASE_DECISION_PATH: ${{ runner.temp }}/full-release-decision/full-release-decision.json
+          DIAGNOSTIC_DRAIN_PATH: ${{ runner.temp }}/full-release-diagnostics/full-release-diagnostic-manifest.json
+        run: node scripts/full-release-validation-state.mjs select
+
+      - name: Verify exact release state artifacts
+        env:
+          RELEASE_PROFILE: ${{ inputs.release_profile }}
+          RERUN_GROUP: ${{ inputs.rerun_group }}
+          TARGET_SHA: ${{ needs.resolve_target.outputs.sha }}
+          RELEASE_EXECUTION_PLAN_PATH: ${{ runner.temp }}/full-release-execution-plan/full-release-execution-plan.json
+          RELEASE_DECISION_PATH: ${{ runner.temp }}/full-release-decision/full-release-decision.json
+          DIAGNOSTIC_DRAIN_PATH: ${{ runner.temp }}/full-release-diagnostics/full-release-diagnostic-manifest.json
+        run: node scripts/full-release-validation-state.mjs verify
 
       - name: Request release evidence update
         if: ${{ inputs.dispatch_release_evidence }}
@@ -1714,17 +1445,18 @@ jobs:
           TARGET_REF: ${{ inputs.ref }}
           PACKAGE_SPEC: ${{ inputs.evidence_package_spec || inputs.npm_telegram_package_spec }}
           GITHUB_RUN_ID_VALUE: ${{ github.run_id }}
-          RELEASE_CHECKS_RESULT: ${{ needs.release_checks.result }}
-          EVIDENCE_REUSE: ${{ needs.evidence_reuse.outputs.reuse }}
-          EVIDENCE_ROOT_RUN_ID: ${{ needs.evidence_reuse.outputs.evidence_root_run_id }}
-          EVIDENCE_POLICY: ${{ needs.evidence_reuse.outputs.evidence_policy }}
+          RELEASE_EXECUTION_PLAN_PATH: ${{ runner.temp }}/full-release-execution-plan/full-release-execution-plan.json
         run: |
           set -euo pipefail
-          if [[ "$RELEASE_CHECKS_RESULT" == "skipped" && "$EVIDENCE_REUSE" != "true" ]]; then
+          EVIDENCE_REUSE="$(jq -r '.evidenceReuse.requested' "$RELEASE_EXECUTION_PLAN_PATH")"
+          EVIDENCE_ROOT_RUN_ID="$(jq -r '.evidenceReuse.rootRunId // ""' "$RELEASE_EXECUTION_PLAN_PATH")"
+          EVIDENCE_POLICY="$(jq -r '.evidenceReuse.policy // ""' "$RELEASE_EXECUTION_PLAN_PATH")"
+          RELEASE_CHECKS_SELECTED="$(jq -r '.children[] | select(.key == "releaseChecks") | .selected' "$RELEASE_EXECUTION_PLAN_PATH")"
+          if [[ "$RELEASE_CHECKS_SELECTED" != "true" && "$EVIDENCE_REUSE" != "true" ]]; then
             echo "Release checks were skipped by rerun group; skipping automatic release evidence update."
             exit 0
           fi
-          notes="Automatically requested by Full Release Validation ${GITHUB_RUN_ID_VALUE} after child workflows completed; the parent summary re-checks current child run conclusions."
+          notes="Automatically requested by Full Release Validation ${GITHUB_RUN_ID_VALUE} after exact Release Decision and Diagnostic Drain artifacts passed shared policy verification."
           if [[ "$EVIDENCE_REUSE" == "true" && -n "${EVIDENCE_ROOT_RUN_ID// }" ]]; then
             notes="Automatically requested by Full Release Validation ${GITHUB_RUN_ID_VALUE}, which reused green product evidence from chain-root run ${EVIDENCE_ROOT_RUN_ID} under policy ${EVIDENCE_POLICY}."
           fi
@@ -1796,23 +1528,9 @@ jobs:
         if: ${{ success() }}
         env:
           TARGET_REF: ${{ startsWith(github.ref, 'refs/heads/release-ci/') && needs.resolve_target.outputs.sha || inputs.ref }}
-          TARGET_SHA: ${{ needs.resolve_target.outputs.sha }}
           RELEASE_PROFILE: ${{ inputs.release_profile }}
           RERUN_GROUP: ${{ inputs.rerun_group }}
           RUN_RELEASE_SOAK: ${{ inputs.run_release_soak || inputs.release_profile == 'stable' || inputs.release_profile == 'full' }}
-          NORMAL_CI_RUN_ID: ${{ needs.normal_ci.outputs.run_id }}
-          PLUGIN_PRERELEASE_RUN_ID: ${{ needs.plugin_prerelease.outputs.run_id }}
-          RELEASE_CHECKS_RUN_ID: ${{ needs.release_checks.outputs.run_id }}
-          NPM_TELEGRAM_RUN_ID: ${{ needs.npm_telegram.outputs.run_id }}
-          PERFORMANCE_RUN_ID: ${{ needs.performance.outputs.run_id }}
-          PERFORMANCE_CONCLUSION: ${{ needs.performance.outputs.conclusion }}
-          EVIDENCE_REUSE: ${{ needs.evidence_reuse.outputs.reuse }}
-          EVIDENCE_RUN_ID: ${{ needs.evidence_reuse.outputs.evidence_run_id }}
-          EVIDENCE_ROOT_RUN_ID: ${{ needs.evidence_reuse.outputs.evidence_root_run_id }}
-          EVIDENCE_SHA: ${{ needs.evidence_reuse.outputs.evidence_sha }}
-          EVIDENCE_POLICY: ${{ needs.evidence_reuse.outputs.evidence_policy }}
-          EVIDENCE_CHANGED_PATHS: ${{ needs.evidence_reuse.outputs.changed_paths }}
-          EVIDENCE_MANIFEST: ${{ needs.evidence_reuse.outputs.evidence_manifest }}
           PROVIDER: ${{ inputs.provider }}
           MODE: ${{ inputs.mode }}
           TARGET_CONTEXT_REF: ${{ inputs.target_context_ref }}
@@ -1827,10 +1545,28 @@ jobs:
           SKIP_PACKAGE_TELEGRAM_E2E: ${{ inputs.skip_package_telegram_e2e }}
           ALLOW_UNRELEASED_CHANGELOG: ${{ inputs.allow_unreleased_changelog || (inputs.target_context_ref == '' && (inputs.ref == 'main' || inputs.ref == 'refs/heads/main')) }}
           PLUGIN_PRERELEASE_NODE_EXCLUDE_PATTERNS_JSON: ${{ inputs.plugin_prerelease_node_exclude_patterns_json }}
+          RELEASE_EXECUTION_PLAN_PATH: ${{ runner.temp }}/full-release-execution-plan/full-release-execution-plan.json
+          DIAGNOSTIC_DRAIN_PATH: ${{ runner.temp }}/full-release-diagnostics/full-release-diagnostic-manifest.json
         run: |
           set -euo pipefail
           manifest_dir="${RUNNER_TEMP}/full-release-validation"
           mkdir -p "$manifest_dir"
+          TARGET_SHA="$(jq -r '.targetSha' "$RELEASE_EXECUTION_PLAN_PATH")"
+          NORMAL_CI_RUN_ID="$(jq -r '.children[] | select(.key == "normalCi") | .runId' "$RELEASE_EXECUTION_PLAN_PATH")"
+          PLUGIN_PRERELEASE_RUN_ID="$(jq -r '.children[] | select(.key == "pluginPrerelease") | .runId' "$RELEASE_EXECUTION_PLAN_PATH")"
+          RELEASE_CHECKS_RUN_ID="$(jq -r '.children[] | select(.key == "releaseChecks") | .runId' "$RELEASE_EXECUTION_PLAN_PATH")"
+          NPM_TELEGRAM_RUN_ID="$(jq -r '.children[] | select(.key == "npmTelegram") | .runId' "$RELEASE_EXECUTION_PLAN_PATH")"
+          PERFORMANCE_RUN_ID="$(jq -r '.children[] | select(.key == "productPerformance") | .runId' "$RELEASE_EXECUTION_PLAN_PATH")"
+          EXECUTION_PLAN_SHA256="$(jq -r '.sha256' "$RELEASE_EXECUTION_PLAN_PATH")"
+          SOURCE_PARENT_RUN_ATTEMPT="$(jq -r '.parentRunAttempt' "$RELEASE_EXECUTION_PLAN_PATH")"
+          EVIDENCE_REUSE="$(jq -r '.evidenceReuse.requested' "$RELEASE_EXECUTION_PLAN_PATH")"
+          EVIDENCE_RUN_ID="$(jq -r '.evidenceReuse.selectedRunId // ""' "$RELEASE_EXECUTION_PLAN_PATH")"
+          EVIDENCE_ROOT_RUN_ID="$(jq -r '.evidenceReuse.rootRunId // ""' "$RELEASE_EXECUTION_PLAN_PATH")"
+          EVIDENCE_SHA="$(jq -r '.evidenceReuse.evidenceSha // ""' "$RELEASE_EXECUTION_PLAN_PATH")"
+          EVIDENCE_POLICY="$(jq -r '.evidenceReuse.policy // ""' "$RELEASE_EXECUTION_PLAN_PATH")"
+          EVIDENCE_CHANGED_PATHS="$(jq -c '.evidenceReuse.changedPaths // []' "$RELEASE_EXECUTION_PLAN_PATH")"
+          EVIDENCE_MANIFEST="$(jq -c '.evidenceReuse.sourceManifest // empty' "$RELEASE_EXECUTION_PLAN_PATH")"
+          PERFORMANCE_CONCLUSION="$(jq -r '.children.productPerformance.conclusion // ""' "$DIAGNOSTIC_DRAIN_PATH")"
           if [[ "$EVIDENCE_REUSE" == "true" ]]; then
             # Inherit the evidence manifest (profile, soak, child runs) so future
             # reuse lookups and evidence consumers keep resolving the chain root.
@@ -1847,6 +1583,8 @@ jobs:
               --arg evidenceRootRunId "$EVIDENCE_ROOT_RUN_ID" \
               --arg evidenceSha "$EVIDENCE_SHA" \
               --arg evidencePolicy "$EVIDENCE_POLICY" \
+              --arg executionPlanSha256 "$EXECUTION_PLAN_SHA256" \
+              --arg sourceParentRunAttempt "$SOURCE_PARENT_RUN_ATTEMPT" \
               --argjson evidenceChangedPaths "$EVIDENCE_CHANGED_PATHS" \
               '. + {
                 version: 3,
@@ -1867,7 +1605,9 @@ jobs:
                 },
                 controls: ((.controls // {}) + {
                   performanceReportPublication: "artifact-only"
-                })
+                }),
+                executionPlanSha256: $executionPlanSha256,
+                sourceParentRunAttempt: ($sourceParentRunAttempt | tonumber)
               }' <<< "$EVIDENCE_MANIFEST" > "${manifest_dir}/full-release-validation-manifest.json"
             exit 0
           fi
@@ -1890,6 +1630,8 @@ jobs:
             --arg npmTelegramRunId "$NPM_TELEGRAM_RUN_ID" \
             --arg performanceRunId "$PERFORMANCE_RUN_ID" \
             --arg performanceConclusion "$PERFORMANCE_CONCLUSION" \
+            --arg executionPlanSha256 "$EXECUTION_PLAN_SHA256" \
+            --arg sourceParentRunAttempt "$SOURCE_PARENT_RUN_ATTEMPT" \
             --arg provider "$PROVIDER" \
             --arg mode "$MODE" \
             --arg targetContextRef "$TARGET_CONTEXT_REF" \
@@ -1918,6 +1660,8 @@ jobs:
               releaseProfile: $releaseProfile,
               rerunGroup: $rerunGroup,
               runReleaseSoak: $runReleaseSoak,
+              executionPlanSha256: $executionPlanSha256,
+              sourceParentRunAttempt: ($sourceParentRunAttempt | tonumber),
               validationInputs: {
                 provider: $provider,
                 mode: $mode,
@@ -1952,6 +1696,15 @@ jobs:
               }
             }' > "${manifest_dir}/full-release-validation-manifest.json"
 
+      - name: Validate release validation manifest
+        env:
+          RELEASE_PROFILE: ${{ inputs.release_profile }}
+          RERUN_GROUP: ${{ inputs.rerun_group }}
+          TARGET_SHA: ${{ needs.resolve_target.outputs.sha }}
+          RELEASE_EXECUTION_PLAN_PATH: ${{ runner.temp }}/full-release-execution-plan/full-release-execution-plan.json
+          RELEASE_VALIDATION_MANIFEST_PATH: ${{ runner.temp }}/full-release-validation/full-release-validation-manifest.json
+        run: node scripts/full-release-validation-state.mjs validate-manifest
+
       - name: Upload release validation manifest
         if: ${{ success() }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
diff --git a/docs/reference/RELEASING.md b/docs/reference/RELEASING.md
index 74bbb84ecf46..80530d158da7 100644
--- a/docs/reference/RELEASING.md
+++ b/docs/reference/RELEASING.md
@@ -410,6 +410,17 @@ The second parent reuses product evidence only when GitHub proves the Release SH
 
 For a fresh Code SHA, the workflow resolves the target, dispatches manual `CI`, then dispatches `OpenClaw Release Checks`. Beta-publish maps to `release_profile=beta` and `run_release_soak=false`; its `all` run excludes broad live/E2E and QA-live lanes. Postpublish-confidence uses the exact published package with soak or explicit focused groups. Stable-publish maps to `release_profile=stable`. The final verifier summary includes slowest-job tables for each child run.
 
+Each dispatcher records the exact child run ID and attempt, then exits. Release
+Decision reports a decisive blocker without waiting for unrelated diagnostic
+tails; with `fail_fast=false`, Diagnostic Drain keeps the selected children
+running to terminal. Diagnose `blocked_diagnostics_running` immediately, but do
+not retry until the drain is terminal. Recover `orchestration_error` against
+the same exact children and never redispatch tests merely to repair collection.
+An immutable run-bound execution plan preserves the original attempt, titles,
+coverage, gates, and child tuples across collector retries. The final verifier
+consumes that plan and the exact attempt-bound Decision and Drain artifacts
+instead of polling or reclassifying child results.
+
 The product-performance child is artifact-only in this release path. The
 umbrella dispatches it with `publish_reports=false`, and validation is rejected
 unless its artifact-only guard proves that the Clawgrit report publisher stayed
diff --git a/docs/reference/full-release-validation.md b/docs/reference/full-release-validation.md
index 447882446dcb..df9c909584e3 100644
--- a/docs/reference/full-release-validation.md
+++ b/docs/reference/full-release-validation.md
@@ -39,12 +39,34 @@ exact alpha tags to the `beta` profile and final versions to `stable`. Pass
 alternate workflow inputs with `-f key=value`; use `-f release_profile=full`
 only for the broad advisory sweep.
 `fail_fast` defaults to `false`, so dispatched child workflows finish and expose
-independent failures together. Pass `-f fail_fast=true` when the shorter
-first-failure cancellation path is preferable.
+independent failures together. In that mode, the parent makes no child
+cancellation calls. Pass `-f fail_fast=true` only when the shorter
+first-failure path is preferable; Release Decision then cancels only the exact
+still-active child that owns the blocking failure.
+
+After dispatch, the parent writes one immutable
+`full-release-execution-plan-<run-id>` artifact. It records selected and
+required coverage, gate results, reuse identity, the original parent attempt,
+and every exact child run ID, attempt, title, workflow ref, and Tooling SHA.
+Decision, Drain, manifest generation, evidence verification, and the final
+verifier consume this artifact. Collector retries restore it and adopt the
+same children; they never rebuild the plan or redispatch tests.
+Release Decision also repeats canonical reuse-chain validation before a reused
+run can pass. The sealed target SHA, evidence SHA, policy, changed-path set,
+selected run, root run, source manifest, trusted tooling identity, and child
+tuple must all still match.
+
+On a parent retry, final verification selects the newest available Release
+Decision and Diagnostic Drain artifacts independently. Both must bind the same
+immutable plan and exact child tuple; their source attempts remain recorded in
+the artifacts and may differ when only one collector needed a retry.
 
 The helper creates a temporary `release-ci/*` ref pinned to the Tooling SHA,
 passes the Validation SHA as both the candidate ref and `expected_sha`, and
-deletes the temporary ref after validation. The Validation SHA equals the Code
+deletes the temporary ref after successful validation and strict evidence
+verification. If Release Decision reports a blocker while Diagnostic Drain is
+still collecting failures, the helper exits nonzero immediately and keeps both
+temporary refs for reruns and diagnosis. The Validation SHA equals the Code
 SHA for product validation or the Release SHA for changelog-only validation; it
 is not a third release identity. The workflow rejects malformed or mismatched
 expected SHAs before child dispatch. Every child must report the same Tooling
@@ -168,7 +190,26 @@ it before dispatching. A narrower `rerun_group` skips this preflight.
 | Release checks          | **Job:** `Run release/live/Docker/QA validation`<br />**Child workflow:** `OpenClaw Release Checks`<br />**Proves:** install smoke, cross-OS package checks, Package Acceptance, and QA Lab parity. QA-live Matrix, Buzz, and Telegram plus gated advisory Discord, WhatsApp, and Slack run for stable/full, beta with `run_release_soak=true`, an explicit `qa-live` controller retry, or the direct child's manual `qa` aggregate. Stable and full profiles also run exhaustive live/E2E suites and Docker release-path chunks.<br />**Rerun:** classify the failed surface and select one concrete release-check group. |
 | Package Telegram        | **Job:** `Run package Telegram E2E`<br />**Child workflow:** `NPM Telegram Beta E2E`<br />**Proves:** a focused published-package Telegram E2E when `release_package_spec` or `npm_telegram_package_spec` is set. Full candidate validation uses the canonical Package Acceptance Telegram E2E instead.<br />**Rerun:** `rerun_group=npm-telegram` with `release_package_spec` or `npm_telegram_package_spec`.                                                                                                                                                                                                             |
 | Product performance     | **Job:** `Run product performance evidence`<br />**Child workflow:** `OpenClaw Performance`<br />**Proves:** release-profile performance run (`profile=release`, `repeat=3`, `fail_on_regression=true`, `publish_reports=false`) against the target SHA. Kova output stays in workflow artifacts and the child must prove its report publisher was skipped. Required (blocking) only for `rerun_group=all` or `rerun_group=performance`; not required for narrower rerun groups.<br />**Rerun:** `rerun_group=performance`.                                                                                                |
-| Umbrella verifier       | **Job:** `Verify full validation`<br />**Child workflow:** none<br />**Proves:** re-checks recorded child run conclusions and appends slowest-job tables from child workflows.<br />**Rerun:** rerun only this job after rerunning a failed child to green.                                                                                                                                                                                                                                                                                                                                                                |
+| Release decision        | **Job:** `Release Decision`<br />**Child workflow:** none<br />**Proves:** polls the exact recorded child run IDs and attempts, enforces release policy, and publishes an attempt-bound decision artifact. A decisive failure becomes `blocked_diagnostics_running` while unrelated child diagnostics continue.<br />**Rerun:** fix or rerun only the blocking surface.                                                                                                                                                                                                                                                    |
+| Diagnostic drain        | **Job:** `Diagnostic Drain`<br />**Child workflow:** none<br />**Proves:** with `fail_fast=false`, follows every selected exact child to terminal without cancellation and writes timing, failed-job, run-attempt, and Tooling-SHA evidence. Collector cancellation instead writes an immediate `cancelled_with_children` handoff containing active child identities.<br />**Rerun:** recover collection only for `orchestration_error`; product failures do not invalidate the drain.                                                                                                                                     |
+| Execution plan          | **Job:** `Seal release execution plan`<br />**Child workflow:** none<br />**Proves:** persists the original parent attempt, exact child identities and titles, required coverage, gates, and reuse identity in a stable run-bound artifact. Attempt-two collector recovery restores this artifact instead of redispatching.<br />**Rerun:** restore the existing plan only; a missing plan is an orchestration error.                                                                                                                                                                                                      |
+| Umbrella verifier       | **Job:** `Verify full validation`<br />**Child workflow:** none<br />**Proves:** downloads the immutable execution plan plus the exact attempt-bound Release Decision and Diagnostic Drain artifacts, verifies their common digest and parent tuple, and accepts only a strict green decision plus terminal drain.<br />**Rerun:** recover the existing collectors or rerun only the failed product surface; the verifier never reclassifies or redispatches children.                                                                                                                                                     |
+
+The five child-dispatch jobs own dispatch and exact identity capture only. They
+emit the child run ID, run attempt, and URL, then finish. Release Decision owns
+the blocking answer; Diagnostic Drain owns complete terminal evidence. The
+immutable execution plan owns child identity across collector attempts. The
+decision state is one of `qualifying`, `blocked_diagnostics_running`, `passed`,
+`blocked_complete`, `orchestration_error`, or `cancelled_with_children`.
+Persistent GitHub API failures are orchestration errors. A child whose workflow
+path, display title, ref, Tooling SHA, run ID, or attempt changes is a distinct
+provenance mismatch.
+
+`blocked_diagnostics_running` is safe for immediate diagnosis but not for a
+retry until Diagnostic Drain is terminal. `orchestration_error` authorizes
+collector recovery against the same exact child identities, never test
+redispatch. `blocked_complete` means diagnostics are complete; it does not
+claim a drain is still running.
 
 The umbrella always dispatches product performance in artifact-only mode.
 `OpenClaw Performance` permits report publication only for scheduled runs or a
@@ -190,9 +231,13 @@ as a transition, it accepts the stable name only for an attempt-1 manifest v2
 producer. It rejects that legacy name for later attempts and manifest v3.
 
 Concurrency is keyed by Validation SHA, Tooling SHA, and rerun group and does
-not cancel an older run. Parent cancellation or timeout leaves an adopted
-identity-checked child running. Cancel that exact child explicitly when it is
-no longer useful.
+not cancel an older run. Parent cancellation or timeout leaves adopted
+identity-checked children running and records `cancelled_with_children` when
+the state collector can complete its cancellation handoff. Cancel an exact
+child explicitly when it is no longer useful. Do not run a second foreground
+watcher when the SHA-pinned helper already owns the parent; use
+`release-ci-summary --watch` only after the helper has returned or when the
+parent was dispatched separately.
 
 ## Release checks stages
 
diff --git a/scripts/full-release-validation-at-sha.mts b/scripts/full-release-validation-at-sha.mts
index 0fa14526230b..dd932898ca82 100644
--- a/scripts/full-release-validation-at-sha.mts
+++ b/scripts/full-release-validation-at-sha.mts
@@ -5,12 +5,17 @@ import {
   spawnSync,
   type ExecFileSyncOptionsWithStringEncoding,
 } from "node:child_process";
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parse as parseYaml } from "yaml";
 import { isRecord as isJsonRecord } from "../packages/normalization-core/src/record-coerce.ts";
+import {
+  classifyReleaseGhTransportError,
+  formatReleaseStateOutcome,
+  validateReleaseStateArtifact,
+} from "./full-release-validation-policy.mjs";
 import { execGhRead } from "./lib/plain-gh.mjs";
 
 const WORKFLOW = "full-release-validation.yml";
@@ -25,6 +30,8 @@ const GH_READ_TIMEOUT_MS = 60_000;
 export const FULL_RELEASE_WAIT_TIMEOUT_MINUTES = 720;
 export const FULL_RELEASE_WAIT_POLL_INTERVAL_MS = 45_000;
 const FULL_RELEASE_PROGRESS_INTERVAL_MS = 5 * 60_000;
+const RELEASE_DECISION_FILE = "full-release-decision.json";
+const MAX_RELEASE_DECISION_BYTES = 128 * 1024;
 const GH_READ_OPTIONS = {
   encoding: "utf8",
   killSignal: "SIGKILL",
@@ -65,7 +72,15 @@ type ReleaseInputs = Record<string, string> &
   Partial<Record<"release_profile" | "allow_unreleased_changelog", string>>;
 type CommandOptions = {
   dryRun?: boolean;
-  stdio?: "inherit" | ["ignore", "pipe" | "ignore", "inherit" | "ignore"];
+  stdio?: "inherit" | ["ignore", "pipe" | "ignore", "pipe" | "inherit" | "ignore"];
+  timeoutMs?: number;
+};
+type CommandStatus = {
+  error?: Error;
+  signal?: unknown;
+  status: number | null;
+  stderr: unknown;
+  stdout: unknown;
 };
 type TemporaryRefParams = {
   keepBranch: boolean;
@@ -89,6 +104,14 @@ function displayValue(value: unknown): string {
   return value === null ? "null" : (JSON.stringify(value) ?? "<undefined>");
 }
 
+function requiredPositiveInteger(value: unknown, label: string): number {
+  const normalized = Number(value);
+  if (!Number.isSafeInteger(normalized) || normalized < 1) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return normalized;
+}
+
 function usage() {
   console.error(`Usage: node scripts/full-release-validation-at-sha.mjs [--sha <target-sha>] [--target-ref <canonical-release-branch-or-tag>] [--workflow-sha <trusted-tooling-sha>] [--trusted-workflow-ref <main-or-release-publish-tag>] [--keep-branch] [--dry-run] [-- -f key=value ...]
 
@@ -100,7 +123,8 @@ workflow lineage through the release evidence manifest, then deletes both
 temporary branches by default. --keep-branch retains both branches. Exact-target and changelog-only Release SHA
 evidence reuse stay enabled; pass -f reuse_evidence=false to force a fresh
 run. Child workflows collect independent failures by default; pass
--f fail_fast=true to cancel each child after its first failed job. The release
+-f fail_fast=true to cancel only an exact still-active child after Release
+Decision identifies a blocking failure for that child. The release
 branch accepts only its final package version or a matching beta prerelease.
 Exact alpha tags remain supported for Tideclaw. The release profile defaults to
 beta for beta candidates and exact alpha tags, and stable otherwise; pass
@@ -124,11 +148,13 @@ function run(command: string, args: string[], options: CommandOptions = {}) {
 function runStatus(command: string, args: string[], options: CommandOptions = {}) {
   if (options.dryRun) {
     console.log(["+", command, ...args].join(" "));
-    return { status: 0, stdout: "" };
+    return { status: 0, stderr: "", stdout: "" };
   }
   return spawnSync(command, args, {
     encoding: "utf8",
+    killSignal: "SIGKILL",
     stdio: options.stdio ?? ["ignore", "pipe", "inherit"],
+    timeout: options.timeoutMs ?? GH_READ_TIMEOUT_MS,
   });
 }
 
@@ -542,6 +568,115 @@ function readActiveParentJobs(parentRunId: string) {
     }));
 }
 
+export function validateReleaseDecisionPayload(
+  payload: unknown,
+  expected: {
+    parentRunAttempt: number;
+    parentRunId: string;
+    workflowSha: string;
+  },
+) {
+  return validateReleaseStateArtifact(
+    payload,
+    {
+      parentRunAttempt: expected.parentRunAttempt,
+      parentRunId: expected.parentRunId,
+      workflowSha: expected.workflowSha,
+    },
+    "decision",
+  );
+}
+
+export function releaseDecisionStopsForeground(state: unknown) {
+  return [
+    "blocked_diagnostics_running",
+    "blocked_complete",
+    "orchestration_error",
+    "cancelled_with_children",
+  ].includes(stringValue(state));
+}
+
+export function tryReadReleaseDecision(
+  parentRunId: string,
+  parentRunAttempt: number,
+  workflowSha: string,
+  runStatusImpl: (
+    command: string,
+    args: string[],
+    options?: CommandOptions,
+  ) => CommandStatus = runStatus,
+) {
+  const artifactName = `full-release-decision-${parentRunId}-${parentRunAttempt}`;
+  const downloadDir = mkdtempSync(join(tmpdir(), "openclaw-release-decision-"));
+  try {
+    const result = runStatusImpl(
+      "gh",
+      [
+        "run",
+        "download",
+        parentRunId,
+        "--repo",
+        "openclaw/openclaw",
+        "--name",
+        artifactName,
+        "--dir",
+        downloadDir,
+      ],
+      { stdio: ["ignore", "ignore", "pipe"], timeoutMs: GH_READ_TIMEOUT_MS },
+    );
+    if (result.status !== 0) {
+      const stderr = stringValue(result.stderr);
+      if (
+        /no valid artifacts found|artifact .* not found|could not find any artifacts/iu.test(stderr)
+      ) {
+        return undefined;
+      }
+      const downloadError = Object.assign(
+        result.error instanceof Error
+          ? result.error
+          : new Error(
+              `Release Decision artifact download failed${
+                stderr.trim() ? `: ${stderr.trim().slice(0, 500)}` : ""
+              }`,
+            ),
+        {
+          signal: result.signal,
+          status: result.status,
+          stderr,
+        },
+      );
+      if (classifyReleaseGhTransportError(downloadError) === "transient") {
+        console.warn(
+          `Release Decision artifact unavailable this poll; retrying: ${downloadError.message}`,
+        );
+        return undefined;
+      }
+      throw new Error(
+        `Release Decision artifact download failed${
+          stderr.trim() ? `: ${stderr.trim().slice(0, 500)}` : ""
+        }`,
+        { cause: downloadError },
+      );
+    }
+    const decisionPath = join(downloadDir, RELEASE_DECISION_FILE);
+    if (!existsSync(decisionPath)) {
+      throw new Error(
+        `Release Decision artifact ${artifactName} omitted ${RELEASE_DECISION_FILE}.`,
+      );
+    }
+    if (statSync(decisionPath).size > MAX_RELEASE_DECISION_BYTES) {
+      throw new Error(`Release Decision artifact ${artifactName} exceeds the size limit.`);
+    }
+    return validateReleaseDecisionPayload(JSON.parse(readFileSync(decisionPath, "utf8")), {
+      parentRunAttempt,
+      parentRunId,
+      workflowSha,
+    });
+  } finally {
+    rmSync(downloadDir, { force: true, recursive: true });
+  }
+}
+
 function waitForWorkflowRun(parentRunId: string, workflowSha: string) {
   let lastSummary = "";
   let consecutiveErrors = 0;
@@ -569,6 +704,18 @@ function waitForWorkflowRun(parentRunId: string, workflowSha: string) {
       console.log(`Parent run status: ${summary}`);
       lastSummary = summary;
     }
+    if (suite) {
+      const releaseDecision = tryReadReleaseDecision(
+        parentRunId,
+        requiredPositiveInteger(suite.run_attempt, "parent run attempt"),
+        workflowSha,
+      );
+      if (releaseDecision && releaseDecisionStopsForeground(releaseDecision.state)) {
+        throw new Error(
+          `${formatReleaseStateOutcome(releaseDecision)}\nhttps://github.com/openclaw/openclaw/actions/runs/${parentRunId}`,
+        );
+      }
+    }
     if (suite?.status === "completed") {
       if (suite.conclusion === "success") {
         return suite;
diff --git a/scripts/full-release-validation-policy.d.mts b/scripts/full-release-validation-policy.d.mts
new file mode 100644
index 000000000000..691a541671e4
--- /dev/null
+++ b/scripts/full-release-validation-policy.d.mts
@@ -0,0 +1,84 @@
+export interface ReleaseRecord {
+  [key: string]: unknown;
+}
+export interface ReleaseChild extends ReleaseRecord {
+  key: string;
+  runAttempt: number | null;
+  runId: string;
+}
+export interface ReleaseExecutionPlan extends ReleaseRecord {
+  children: ReleaseChild[];
+  evidenceReuse: ReleaseRecord;
+  gates: ReleaseRecord[];
+}
+export interface ReleaseStateArtifact extends ReleaseRecord {
+  blockers: ReleaseRecord[];
+  children: Record<string, ReleaseRecord>;
+  errors: ReleaseRecord[];
+  parentRunAttempt: number;
+  sourceParentRunAttempt: number;
+  state: string;
+}
+export type ReleaseGhTransportErrorClass = "hard" | "transient";
+export function classifyReleaseGhTransportError(error: unknown): ReleaseGhTransportErrorClass;
+export function buildReleaseExecutionPlan(input: ReleaseRecord): {
+  children: ReleaseChild[];
+  gates: ReleaseRecord[];
+};
+export function buildReleaseExecutionPlanArtifact(input: ReleaseRecord): ReleaseExecutionPlan;
+export function validateReleaseExecutionPlanArtifact(
+  payload: unknown,
+  expected?: Record<string, unknown>,
+): ReleaseExecutionPlan;
+export function releaseExecutionPlanSha256(plan: ReleaseRecord): string;
+
+export function terminalPolicyPass(
+  child: ReleaseRecord,
+  releaseProfile: string,
+  workflowRef: string,
+): boolean;
+
+export function classifyReleaseSnapshot(input: ReleaseRecord): ReleaseStateArtifact;
+export function releasePlanGateFailures(gates: ReleaseRecord[]): ReleaseRecord[];
+export function buildReleaseStateArtifact(input: ReleaseRecord): ReleaseStateArtifact;
+export function validateReleaseStateArtifact(
+  payload: unknown,
+  expected?: Record<string, unknown>,
+  expectedMode?: string,
+): ReleaseStateArtifact;
+export function verifyReleaseStateArtifacts(
+  executionPlanPayload: unknown,
+  decisionPayload: unknown,
+  drainPayload: unknown,
+  expected?: Record<string, unknown>,
+): {
+  decision: ReleaseStateArtifact;
+  drain: ReleaseStateArtifact;
+  executionPlan: ReleaseExecutionPlan;
+  sourceAttempts: {
+    decision: number;
+    drain: number;
+    executionPlan: number;
+  };
+};
+export function selectReleaseStateArtifacts(
+  executionPlanPayload: unknown,
+  decisionCandidates: Array<{ name: string; payload: unknown }>,
+  drainCandidates: Array<{ name: string; payload: unknown }>,
+  expected?: Record<string, unknown>,
+): {
+  decision: ReleaseStateArtifact;
+  drain: ReleaseStateArtifact;
+  executionPlan: ReleaseExecutionPlan;
+  sourceAttempts: {
+    decision: number;
+    drain: number;
+    executionPlan: number;
+  };
+};
+export function formatReleaseStateOutcome(payload: ReleaseRecord): string;
+export function affectedActiveRunIds(
+  children: ReleaseRecord[],
+  blockers: ReleaseRecord[],
+  cancelledRunIds?: Set<string>,
+): string[];
diff --git a/scripts/full-release-validation-policy.mjs b/scripts/full-release-validation-policy.mjs
new file mode 100644
index 000000000000..89d93eb305c1
--- /dev/null
+++ b/scripts/full-release-validation-policy.mjs
@@ -0,0 +1,1019 @@
+import { createHash } from "node:crypto";
+
+const SUCCESSFUL_JOB_CONCLUSIONS = new Set(["neutral", "skipped", "success"]);
+const MAX_REPORTED_ISSUES = 25;
+const MAX_SUMMARY_ISSUES = 5;
+const MAX_LABEL_LENGTH = 200;
+const MAX_MESSAGE_LENGTH = 500;
+const MAX_URL_LENGTH = 1024;
+const EXACT_TARGET_EVIDENCE_REUSE_POLICY = "exact-target-full-validation-v1";
+const CHANGELOG_ONLY_EVIDENCE_REUSE_POLICY = "changelog-only-release-v1";
+const HARD_GH_TRANSPORT_PATTERN =
+  /HTTP (?:401|403)\b|Bad credentials|authentication required|not authenticated|gh auth login|unknown (?:command|flag)|Usage: gh\b|ENOENT|EACCES/iu;
+const TRANSIENT_GH_TRANSPORT_PATTERN =
+  /HTTP 429\b|HTTP 5[0-9][0-9]\b|Server Error|secondary rate limit|API rate limit|abuse detection|error connecting to|context deadline exceeded|connection reset by peer|connection refused|TLS handshake timeout|i\/o timeout|network is unreachable|unexpected EOF|ETIMEDOUT|ECONNRESET|EAI_AGAIN/iu;
+
+const RELEASE_DECISION_STATES = Object.freeze([
+  "qualifying",
+  "blocked_diagnostics_running",
+  "passed",
+  "blocked_complete",
+  "orchestration_error",
+  "cancelled_with_children",
+]);
+
+const RELEASE_DECISION_STATE_SET = new Set(RELEASE_DECISION_STATES);
+const CHILD_SPECS = Object.freeze([
+  {
+    dispatchName: "Dispatch CI",
+    displayName: "CI",
+    key: "normalCi",
+    rerunGroups: ["all", "ci"],
+    suffix: "-ci",
+    workflow: "ci.yml",
+  },
+  {
+    dispatchName: "Dispatch plugin prerelease",
+    displayName: "Plugin Prerelease",
+    key: "pluginPrerelease",
+    rerunGroups: ["all", "plugin-prerelease"],
+    suffix: "-plugin-prerelease",
+    workflow: "plugin-prerelease.yml",
+  },
+  {
+    dispatchName: "Dispatch release checks",
+    displayName: "OpenClaw Release Checks",
+    key: "releaseChecks",
+    rerunGroups: [
+      "all",
+      "install-smoke",
+      "cross-os",
+      "live-e2e",
+      "package",
+      "qa-parity",
+      "qa-live",
+    ],
+    suffix: "-release-checks",
+    workflow: "openclaw-release-checks.yml",
+  },
+  {
+    dispatchName: "Dispatch npm Telegram E2E",
+    displayName: "NPM Telegram Beta E2E",
+    key: "npmTelegram",
+    rerunGroups: ["npm-telegram"],
+    suffix: "-npm-telegram",
+    workflow: "npm-telegram-beta-e2e.yml",
+  },
+  {
+    dispatchName: "Dispatch OpenClaw Performance",
+    displayName: "OpenClaw Performance",
+    key: "productPerformance",
+    rerunGroups: ["all", "performance"],
+    suffix: "",
+    workflow: "openclaw-performance.yml",
+  },
+]);
+
+function releaseGhTransportErrorText(error) {
+  const values = [error];
+  const seen = new Set();
+  const parts = [];
+  while (values.length > 0) {
+    const value = values.shift();
+    if (value && typeof value === "object") {
+      if (seen.has(value)) {
+        continue;
+      }
+      seen.add(value);
+      if (value instanceof Error) {
+        parts.push(value.name, value.message);
+      }
+      for (const key of ["stderr", "stdout", "code", "signal", "cause"]) {
+        if (key in value && value[key] !== undefined) {
+          values.push(value[key]);
+        }
+      }
+      continue;
+    }
+    if (value !== undefined && value !== null) {
+      parts.push(String(value));
+    }
+  }
+  return parts.join("\n");
+}
+
+export function classifyReleaseGhTransportError(error) {
+  const text = releaseGhTransportErrorText(error);
+  if (HARD_GH_TRANSPORT_PATTERN.test(text)) {
+    return "hard";
+  }
+  return TRANSIENT_GH_TRANSPORT_PATTERN.test(text) ? "transient" : "hard";
+}
+
+function stringValue(value, fallback = "") {
+  return typeof value === "string" ? value : fallback;
+}
+
+function boundedString(value, maxLength) {
+  return stringValue(value)
+    .replaceAll(/[\r\n\t]+/gu, " ")
+    .trim()
+    .slice(0, maxLength);
+}
+
+function positiveInteger(value) {
+  const normalized = Number(value);
+  return Number.isSafeInteger(normalized) && normalized > 0 ? normalized : undefined;
+}
+
+function booleanValue(value) {
+  return value === true || value === "true";
+}
+
+function candidatePreparationRequired(input) {
+  if (
+    booleanValue(input.evidenceReuse) ||
+    stringValue(input.releasePackageSpec).trim() ||
+    stringValue(input.packageAcceptancePackageSpec).trim()
+  ) {
+    return false;
+  }
+  if (["all", "plugin-prerelease", "cross-os", "package"].includes(input.rerunGroup)) {
+    return true;
+  }
+  return input.rerunGroup === "live-e2e" && !stringValue(input.liveSuiteFilter).trim();
+}
+
+export function buildReleaseExecutionPlan(input) {
+  const parentRunId = stringValue(input.parentRunId).trim();
+  const parentRunAttempt = positiveInteger(input.parentRunAttempt);
+  const rerunGroup = stringValue(input.rerunGroup).trim();
+  if (!parentRunId || parentRunAttempt === undefined || !rerunGroup) {
+    throw new Error("release execution plan identity is invalid");
+  }
+  const reused = booleanValue(input.evidenceReuse);
+  const childInputs =
+    input.children && typeof input.children === "object" && !Array.isArray(input.children)
+      ? input.children
+      : {};
+  const npmTelegramForAll =
+    rerunGroup === "all" &&
+    Boolean(
+      stringValue(input.npmTelegramPackageSpec).trim() ||
+      stringValue(input.releasePackageSpec).trim(),
+    );
+  const children = CHILD_SPECS.map((spec) => {
+    const raw = childInputs[spec.key] ?? {};
+    const required =
+      spec.key === "npmTelegram"
+        ? rerunGroup === "npm-telegram" || npmTelegramForAll
+        : spec.rerunGroups.includes(rerunGroup);
+    const dispatchId = `full-release-validation-${parentRunId}-${parentRunAttempt}${spec.suffix}`;
+    return {
+      dispatchName: spec.dispatchName,
+      displayTitle: `${spec.displayName} ${dispatchId}`,
+      key: spec.key,
+      required,
+      result: stringValue(raw.result, "skipped"),
+      runAttempt: positiveInteger(raw.runAttempt) ?? null,
+      runId: stringValue(raw.runId).trim(),
+      selected: required,
+      source: reused ? "reused" : "fresh",
+      url: stringValue(raw.url).trim(),
+      workflow: spec.workflow,
+      workflowRef: stringValue(input.workflowRef).trim(),
+      workflowSha: stringValue(input.workflowSha).trim(),
+    };
+  });
+  const gates = [
+    {
+      name: "Resolve target ref",
+      required: true,
+      result: stringValue(input.resolveTargetResult, "missing"),
+    },
+    {
+      name: "Verify Docker runtime image assets",
+      required: !reused && rerunGroup === "all",
+      result: stringValue(input.dockerPreflightResult, "skipped"),
+    },
+    {
+      name: "Prepare shared release candidate",
+      required: candidatePreparationRequired(input),
+      result: stringValue(input.prepareCandidateResult, "skipped"),
+    },
+  ];
+  return { children, gates };
+}
+
+function normalizedGate(gate) {
+  return {
+    name: boundedString(gate?.name, MAX_LABEL_LENGTH),
+    required: gate?.required === true,
+    result: boundedString(gate?.result, MAX_LABEL_LENGTH),
+  };
+}
+
+function normalizedEvidenceReuse(evidenceReuse) {
+  if (!evidenceReuse || evidenceReuse.requested !== true) {
+    return { requested: false };
+  }
+  return {
+    changedPaths: Array.isArray(evidenceReuse.changedPaths)
+      ? evidenceReuse.changedPaths
+          .map((value) => boundedString(value, MAX_LABEL_LENGTH))
+          .filter(Boolean)
+      : [],
+    evidenceSha: boundedString(evidenceReuse.evidenceSha, MAX_LABEL_LENGTH),
+    policy: boundedString(evidenceReuse.policy, MAX_LABEL_LENGTH),
+    requested: true,
+    rootRunId: boundedString(evidenceReuse.rootRunId, MAX_LABEL_LENGTH),
+    runUrl: boundedString(evidenceReuse.runUrl, MAX_URL_LENGTH),
+    selectedRunId: boundedString(evidenceReuse.selectedRunId, MAX_LABEL_LENGTH),
+    sourceManifest:
+      evidenceReuse.sourceManifest &&
+      typeof evidenceReuse.sourceManifest === "object" &&
+      !Array.isArray(evidenceReuse.sourceManifest)
+        ? structuredClone(evidenceReuse.sourceManifest)
+        : null,
+  };
+}
+
+function validEvidenceReuseIdentity(evidenceReuse) {
+  if (!evidenceReuse.requested) {
+    return true;
+  }
+  const validChangedPaths =
+    (evidenceReuse.policy === EXACT_TARGET_EVIDENCE_REUSE_POLICY &&
+      evidenceReuse.changedPaths.length === 0) ||
+    (evidenceReuse.policy === CHANGELOG_ONLY_EVIDENCE_REUSE_POLICY &&
+      evidenceReuse.changedPaths.length === 1 &&
+      evidenceReuse.changedPaths[0] === "CHANGELOG.md");
+  return (
+    /^[a-f0-9]{40}$/u.test(evidenceReuse.evidenceSha) &&
+    /^[1-9][0-9]*$/u.test(evidenceReuse.rootRunId) &&
+    /^[1-9][0-9]*$/u.test(evidenceReuse.selectedRunId) &&
+    evidenceReuse.sourceManifest !== null &&
+    validChangedPaths
+  );
+}
+
+function normalizedTrustedWorkflow(identity) {
+  const ref = boundedString(identity?.ref, MAX_LABEL_LENGTH);
+  const fullRef = boundedString(identity?.fullRef, MAX_LABEL_LENGTH);
+  const sha = boundedString(identity?.sha, MAX_LABEL_LENGTH);
+  if (
+    !ref ||
+    !/^[a-f0-9]{40}$/u.test(sha) ||
+    (fullRef !== `refs/heads/${ref}` && fullRef !== `refs/tags/${ref}`)
+  ) {
+    throw new Error("release execution plan trusted workflow identity is invalid");
+  }
+  return { fullRef, ref, sha };
+}
+
+function executionPlanDigestPayload(plan) {
+  return {
+    blockers: plan.blockers,
+    children: plan.children,
+    errors: plan.errors,
+    evidenceReuse: plan.evidenceReuse,
+    gates: plan.gates,
+    kind: plan.kind,
+    parentRunAttempt: plan.parentRunAttempt,
+    parentRunId: plan.parentRunId,
+    releaseProfile: plan.releaseProfile,
+    rerunGroup: plan.rerunGroup,
+    targetSha: plan.targetSha,
+    trustedWorkflow: plan.trustedWorkflow,
+    version: plan.version,
+    workflowRef: plan.workflowRef,
+    workflowSha: plan.workflowSha,
+  };
+}
+
+export function releaseExecutionPlanSha256(plan) {
+  return createHash("sha256")
+    .update(JSON.stringify(executionPlanDigestPayload(plan)))
+    .digest("hex");
+}
+
+export function buildReleaseExecutionPlanArtifact({
+  blockers = [],
+  children,
+  errors = [],
+  evidenceReuse,
+  expected,
+  gates,
+  releaseProfile,
+  rerunGroup,
+  trustedWorkflow,
+}) {
+  const normalizedReuse = normalizedEvidenceReuse(evidenceReuse);
+  if (!validEvidenceReuseIdentity(normalizedReuse)) {
+    throw new Error("release execution plan evidence reuse binding is invalid");
+  }
+  const plan = {
+    version: 1,
+    kind: "openclaw.full-release-execution-plan",
+    parentRunId: String(expected.parentRunId),
+    parentRunAttempt: positiveInteger(expected.parentRunAttempt),
+    workflowRef: boundedString(expected.workflowRef, MAX_LABEL_LENGTH),
+    workflowSha: boundedString(expected.workflowSha, MAX_LABEL_LENGTH),
+    targetSha: boundedString(expected.targetSha, MAX_LABEL_LENGTH),
+    trustedWorkflow: normalizedTrustedWorkflow(trustedWorkflow),
+    releaseProfile: boundedString(releaseProfile, MAX_LABEL_LENGTH),
+    rerunGroup: boundedString(rerunGroup, MAX_LABEL_LENGTH),
+    evidenceReuse: normalizedReuse,
+    gates: gates.map(normalizedGate),
+    children: children.map(normalizedPlanChild),
+    blockers: normalizeIssues(blockers, "release_blocker"),
+    errors: normalizeIssues(errors, "orchestration_error"),
+  };
+  return { ...plan, sha256: releaseExecutionPlanSha256(plan) };
+}
+
+export function validateReleaseExecutionPlanArtifact(payload, expected = {}) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("release execution plan artifact is invalid");
+  }
+  if (
+    payload.version !== 1 ||
+    payload.kind !== "openclaw.full-release-execution-plan" ||
+    !/^[1-9][0-9]*$/u.test(String(payload.parentRunId ?? "")) ||
+    positiveInteger(payload.parentRunAttempt) === undefined ||
+    !/^[a-f0-9]{40}$/u.test(String(payload.workflowSha ?? "")) ||
+    (payload.targetSha !== "" && !/^[a-f0-9]{40}$/u.test(String(payload.targetSha ?? ""))) ||
+    (expected.parentRunId !== undefined &&
+      String(payload.parentRunId) !== String(expected.parentRunId)) ||
+    (expected.maxParentRunAttempt !== undefined &&
+      Number(payload.parentRunAttempt) > Number(expected.maxParentRunAttempt)) ||
+    (expected.workflowRef !== undefined && payload.workflowRef !== expected.workflowRef) ||
+    (expected.workflowSha !== undefined && payload.workflowSha !== expected.workflowSha) ||
+    (expected.releaseProfile !== undefined && payload.releaseProfile !== expected.releaseProfile) ||
+    (expected.rerunGroup !== undefined && payload.rerunGroup !== expected.rerunGroup) ||
+    (expected.targetSha !== undefined && payload.targetSha !== expected.targetSha)
+  ) {
+    throw new Error("release execution plan artifact binding is invalid");
+  }
+  const evidenceReuse = normalizedEvidenceReuse(payload.evidenceReuse);
+  if (!validEvidenceReuseIdentity(evidenceReuse)) {
+    throw new Error("release execution plan evidence reuse binding is invalid");
+  }
+  const trustedWorkflow = normalizedTrustedWorkflow(payload.trustedWorkflow);
+  const plan = {
+    ...payload,
+    parentRunAttempt: positiveInteger(payload.parentRunAttempt),
+    parentRunId: String(payload.parentRunId),
+    children: validatePlan(payload.children),
+    blockers: normalizeIssues(payload.blockers, "release_blocker"),
+    errors: normalizeIssues(payload.errors, "orchestration_error"),
+    evidenceReuse,
+    gates: Array.isArray(payload.gates) ? payload.gates.map(normalizedGate) : [],
+    trustedWorkflow,
+  };
+  const sha256 = releaseExecutionPlanSha256(plan);
+  if (payload.sha256 !== sha256) {
+    throw new Error("release execution plan artifact digest is invalid");
+  }
+  return { ...plan, sha256 };
+}
+
+function normalizeIssue(issue, fallbackKind) {
+  return {
+    child: boundedString(issue?.child, MAX_LABEL_LENGTH),
+    conclusion: boundedString(issue?.conclusion, MAX_LABEL_LENGTH),
+    job: boundedString(issue?.job, MAX_LABEL_LENGTH),
+    kind: boundedString(issue?.kind, MAX_LABEL_LENGTH) || fallbackKind,
+    message: boundedString(issue?.message, MAX_MESSAGE_LENGTH),
+    runId: boundedString(issue?.runId, MAX_LABEL_LENGTH),
+    url: boundedString(issue?.url, MAX_URL_LENGTH),
+  };
+}
+
+function normalizeIssues(issues, fallbackKind) {
+  return (Array.isArray(issues) ? issues : [])
+    .slice(0, MAX_REPORTED_ISSUES)
+    .map((issue) => normalizeIssue(issue, fallbackKind));
+}
+
+function isReleaseCheckJobAdvisory({ jobName, releaseProfile, workflowRef }) {
+  if (
+    jobName.startsWith("Run QA Lab parity lane (") ||
+    jobName === "Run QA Lab parity report" ||
+    jobName.startsWith("Run QA Lab runtime-pair lane (") ||
+    jobName === "Verify QA Lab runtime-pair lanes" ||
+    jobName === "Run QA Lab live Discord lane" ||
+    jobName === "Run QA Lab live WhatsApp lane" ||
+    jobName === "Run QA Lab live Slack lane"
+  ) {
+    return true;
+  }
+  if (/^tideclaw\/alpha\/[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{4}Z$/u.test(workflowRef)) {
+    return !(
+      jobName === "resolve_target" ||
+      jobName === "Prepare release package artifact" ||
+      jobName.startsWith("install_smoke_release_checks / ") ||
+      jobName === "Run package acceptance" ||
+      jobName.startsWith("Run package acceptance / ")
+    );
+  }
+  return (
+    releaseProfile === "beta" &&
+    (jobName.startsWith("Run package acceptance / Telegram package acceptance / ") ||
+      (jobName.startsWith("Run repo/live E2E validation / ") &&
+        (jobName.includes("Docker live") ||
+          jobName.includes("Live media suites") ||
+          jobName.includes("validate_live_provider_suites") ||
+          jobName.includes("validate_release_live_cache") ||
+          jobName.includes("prepare_live_test_image"))))
+  );
+}
+
+function failedJobsForPolicy(child, releaseProfile, workflowRef) {
+  return child.jobs.filter((job) => {
+    if (
+      job.status !== "completed" ||
+      SUCCESSFUL_JOB_CONCLUSIONS.has(String(job.conclusion ?? ""))
+    ) {
+      return false;
+    }
+    if (child.key === "releaseChecks") {
+      return !isReleaseCheckJobAdvisory({
+        jobName: stringValue(job.name),
+        releaseProfile,
+        workflowRef,
+      });
+    }
+    return !(child.key === "productPerformance" && releaseProfile === "beta");
+  });
+}
+
+export function terminalPolicyPass(child, releaseProfile, workflowRef) {
+  if (child.status !== "completed") {
+    return false;
+  }
+  if (child.conclusion === "success") {
+    return true;
+  }
+  if (child.key === "productPerformance" && releaseProfile === "beta") {
+    return true;
+  }
+  if (child.key === "releaseChecks") {
+    const verifier = child.jobs.find((job) => job.name === "Verify release checks");
+    return (
+      verifier?.status === "completed" &&
+      verifier.conclusion === "success" &&
+      failedJobsForPolicy(child, releaseProfile, workflowRef).length === 0
+    );
+  }
+  return false;
+}
+
+function dispatchMissingBlockers(children) {
+  return children
+    .filter(
+      (child) =>
+        child.required &&
+        child.selected &&
+        (!/^[1-9][0-9]*$/u.test(String(child.runId ?? "")) ||
+          positiveInteger(child.runAttempt) === undefined),
+    )
+    .map((child) => ({
+      child: child.key,
+      conclusion: stringValue(child.result, "missing"),
+      job: child.dispatchName || `Dispatch ${child.key}`,
+      kind: "dispatch_missing",
+      message: `${child.key} required dispatch did not record an exact run ID and attempt`,
+      runId: stringValue(child.runId),
+      url: stringValue(child.url),
+    }));
+}
+
+function dispatchResultBlockers(children) {
+  return children
+    .filter(
+      (child) =>
+        child.required && child.selected && child.source === "fresh" && child.result !== "success",
+    )
+    .map((child) => ({
+      child: child.key,
+      conclusion: stringValue(child.result, "missing"),
+      job: child.dispatchName || `Dispatch ${child.key}`,
+      kind: "dispatch_failed",
+      message: `${child.key} required dispatch ended with ${stringValue(child.result, "missing")}`,
+      runId: stringValue(child.runId),
+      url: stringValue(child.url),
+    }));
+}
+
+export function classifyReleaseSnapshot({
+  cancelled = false,
+  children,
+  extraBlockers = [],
+  extraErrors = [],
+  localFailures = [],
+  releaseProfile,
+  workflowRef,
+}) {
+  const selected = children.filter((child) => child.selected);
+  const active = selected.filter(
+    (child) => child.runId && child.runAttempt && child.status !== "completed",
+  );
+  const childErrors = selected.flatMap((child) =>
+    (child.errors ?? []).filter((error) => error.kind !== "dispatch_missing"),
+  );
+  const childJobBlockers = selected.flatMap((child) =>
+    failedJobsForPolicy(child, releaseProfile, workflowRef).map((job) => ({
+      child: child.key,
+      conclusion: job.conclusion,
+      job: job.name,
+      kind: "job_failure",
+      message: `${child.key} job failed policy`,
+      runId: child.runId,
+      url: job.html_url ?? job.url ?? child.url,
+    })),
+  );
+  const childJobBlockerKeys = new Set(
+    childJobBlockers.map((blocker) => `${blocker.child}:${blocker.runId}`),
+  );
+  const terminalBlockers = selected
+    .filter(
+      (child) =>
+        child.runId &&
+        child.runAttempt &&
+        child.status === "completed" &&
+        !terminalPolicyPass(child, releaseProfile, workflowRef) &&
+        !childJobBlockerKeys.has(`${child.key}:${child.runId}`),
+    )
+    .map((child) => ({
+      child: child.key,
+      conclusion: child.conclusion,
+      job: "<workflow>",
+      kind: "workflow_failure",
+      message: `${child.key} workflow failed release policy`,
+      runId: child.runId,
+      url: child.url,
+    }));
+  const blockers = normalizeIssues(
+    [
+      ...localFailures,
+      ...extraBlockers,
+      ...dispatchMissingBlockers(selected),
+      ...dispatchResultBlockers(selected),
+      ...childJobBlockers,
+      ...terminalBlockers,
+    ],
+    "release_blocker",
+  );
+  const errors = normalizeIssues([...extraErrors, ...childErrors], "orchestration_error");
+
+  let state;
+  if (cancelled && active.length > 0) {
+    state = "cancelled_with_children";
+  } else if (errors.length > 0) {
+    state = "orchestration_error";
+  } else if (blockers.length > 0) {
+    state = active.length > 0 ? "blocked_diagnostics_running" : "blocked_complete";
+  } else if (active.length > 0) {
+    state = "qualifying";
+  } else {
+    state = "passed";
+  }
+
+  return {
+    activeRunIds: active.map((child) => String(child.runId)),
+    blockers,
+    errors,
+    state,
+  };
+}
+
+function childTiming(child) {
+  const started = Date.parse(child.createdAt);
+  const updated = Date.parse(child.updatedAt);
+  return {
+    durationMinutes:
+      Number.isFinite(started) && Number.isFinite(updated)
+        ? Math.round(((updated - started) / 60_000) * 10) / 10
+        : null,
+    jobs: child.jobs.map((job) => {
+      const jobStarted = Date.parse(job.started_at);
+      const jobCompleted = Date.parse(job.completed_at);
+      return {
+        conclusion: stringValue(job.conclusion),
+        durationMinutes:
+          Number.isFinite(jobStarted) && Number.isFinite(jobCompleted)
+            ? Math.round(((jobCompleted - jobStarted) / 60_000) * 10) / 10
+            : null,
+        name: boundedString(job.name, MAX_LABEL_LENGTH),
+        startedAt: stringValue(job.started_at),
+        status: stringValue(job.status),
+        url: boundedString(job.html_url ?? job.url, MAX_URL_LENGTH),
+      };
+    }),
+  };
+}
+
+function normalizedPlanChild(child) {
+  return {
+    dispatchName: boundedString(child.dispatchName, MAX_LABEL_LENGTH),
+    displayTitle: boundedString(child.displayTitle, MAX_LABEL_LENGTH),
+    key: boundedString(child.key, MAX_LABEL_LENGTH),
+    required: child.required === true,
+    result: boundedString(child.result, MAX_LABEL_LENGTH),
+    runAttempt: positiveInteger(child.runAttempt) ?? null,
+    runId: boundedString(child.runId, MAX_LABEL_LENGTH),
+    selected: child.selected === true,
+    source: child.source === "reused" ? "reused" : "fresh",
+    url: boundedString(child.url, MAX_URL_LENGTH),
+    workflow: boundedString(child.workflow, MAX_LABEL_LENGTH),
+    workflowRef: boundedString(child.workflowRef, MAX_LABEL_LENGTH),
+    workflowSha: boundedString(child.workflowSha, MAX_LABEL_LENGTH),
+  };
+}
+
+export function buildReleaseStateArtifact({
+  cancellation = {},
+  children,
+  decision,
+  executionPlan,
+  expected,
+  mode,
+  releaseProfile,
+  rerunGroup,
+}) {
+  return {
+    version: 2,
+    kind:
+      mode === "decision"
+        ? "openclaw.full-release-decision"
+        : "openclaw.full-release-diagnostic-drain",
+    mode,
+    parentRunId: expected.parentRunId,
+    parentRunAttempt: expected.parentRunAttempt,
+    sourceParentRunAttempt: executionPlan.parentRunAttempt,
+    workflowRef: expected.workflowRef,
+    workflowSha: expected.workflowSha,
+    targetSha: expected.targetSha,
+    releaseProfile,
+    rerunGroup,
+    executionPlanSha256: executionPlan.sha256,
+    state: decision.state,
+    activeRunIds: decision.activeRunIds,
+    blockers: decision.blockers,
+    errors: decision.errors,
+    cancellation: {
+      cancelledRunIds: [...(cancellation.cancelledRunIds ?? [])].map(String),
+      requested: cancellation.requested === true,
+    },
+    children: Object.fromEntries(
+      children
+        .filter((child) => child.selected && child.runId && child.runAttempt)
+        .map((child) => [
+          child.key,
+          {
+            conclusion: stringValue(child.conclusion),
+            displayTitle: boundedString(child.displayTitle, MAX_LABEL_LENGTH),
+            errors: normalizeIssues(child.errors, "orchestration_error"),
+            runAttempt: positiveInteger(child.runAttempt),
+            runId: String(child.runId),
+            status: stringValue(child.status),
+            timing: childTiming(child),
+            url: boundedString(child.url, MAX_URL_LENGTH),
+            workflow: boundedString(child.workflow, MAX_LABEL_LENGTH),
+            workflowRef: boundedString(child.workflowRef, MAX_LABEL_LENGTH),
+            workflowSha: boundedString(child.workflowSha, MAX_LABEL_LENGTH),
+          },
+        ]),
+    ),
+  };
+}
+
+function validatePlan(value) {
+  if (!Array.isArray(value)) {
+    throw new Error("release state plan is invalid");
+  }
+  const keys = new Set();
+  return value.map((child) => {
+    const normalized = normalizedPlanChild(child);
+    if (
+      !normalized.key ||
+      !normalized.workflow ||
+      !normalized.displayTitle ||
+      !normalized.dispatchName ||
+      keys.has(normalized.key) ||
+      (normalized.required && !normalized.selected)
+    ) {
+      throw new Error("release state child plan is invalid");
+    }
+    keys.add(normalized.key);
+    return normalized;
+  });
+}
+
+export function validateReleaseStateArtifact(payload, expected, expectedMode) {
+  const expectedValues = expected ?? {};
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("release state artifact is invalid");
+  }
+  const mode = expectedMode ?? payload.mode;
+  const expectedKind =
+    mode === "decision"
+      ? "openclaw.full-release-decision"
+      : "openclaw.full-release-diagnostic-drain";
+  if (
+    payload.version !== 2 ||
+    payload.mode !== mode ||
+    payload.kind !== expectedKind ||
+    !RELEASE_DECISION_STATE_SET.has(stringValue(payload.state)) ||
+    !/^[a-f0-9]{64}$/u.test(String(payload.executionPlanSha256 ?? "")) ||
+    positiveInteger(payload.parentRunAttempt) === undefined ||
+    positiveInteger(payload.sourceParentRunAttempt) === undefined ||
+    (expectedValues.parentRunId !== undefined &&
+      String(payload.parentRunId) !== String(expectedValues.parentRunId)) ||
+    (expectedValues.parentRunAttempt !== undefined &&
+      Number(payload.parentRunAttempt) !== Number(expectedValues.parentRunAttempt)) ||
+    (expectedValues.maxParentRunAttempt !== undefined &&
+      Number(payload.parentRunAttempt) > Number(expectedValues.maxParentRunAttempt)) ||
+    (expectedValues.workflowRef !== undefined &&
+      payload.workflowRef !== expectedValues.workflowRef) ||
+    (expectedValues.workflowSha !== undefined &&
+      payload.workflowSha !== expectedValues.workflowSha) ||
+    (expectedValues.targetSha !== undefined && payload.targetSha !== expectedValues.targetSha) ||
+    (expectedValues.releaseProfile !== undefined &&
+      payload.releaseProfile !== expectedValues.releaseProfile) ||
+    (expectedValues.rerunGroup !== undefined && payload.rerunGroup !== expectedValues.rerunGroup)
+  ) {
+    throw new Error("release state artifact binding is invalid");
+  }
+  const blockers = normalizeIssues(payload.blockers, "release_blocker");
+  const errors = normalizeIssues(payload.errors, "orchestration_error");
+  const activeRunIds = Array.isArray(payload.activeRunIds)
+    ? payload.activeRunIds.map(String).filter((runId) => /^[1-9][0-9]*$/u.test(runId))
+    : [];
+  const children =
+    payload.children && typeof payload.children === "object" && !Array.isArray(payload.children)
+      ? Object.fromEntries(
+          Object.entries(payload.children).map(([key, child]) => {
+            if (!child || typeof child !== "object" || Array.isArray(child)) {
+              throw new Error(`release state child snapshot is invalid: ${key}`);
+            }
+            const timingJobs = Array.isArray(child.timing?.jobs)
+              ? child.timing.jobs.map((job) => ({
+                  conclusion: stringValue(job?.conclusion),
+                  durationMinutes:
+                    typeof job?.durationMinutes === "number" ? job.durationMinutes : null,
+                  name: boundedString(job?.name, MAX_LABEL_LENGTH),
+                  startedAt: stringValue(job?.startedAt),
+                  status: stringValue(job?.status),
+                  url: boundedString(job?.url, MAX_URL_LENGTH),
+                }))
+              : [];
+            return [
+              key,
+              {
+                conclusion: stringValue(child.conclusion),
+                displayTitle: boundedString(child.displayTitle, MAX_LABEL_LENGTH),
+                errors: normalizeIssues(child.errors, "orchestration_error"),
+                runAttempt: positiveInteger(child.runAttempt),
+                runId: String(child.runId ?? ""),
+                status: stringValue(child.status),
+                timing: {
+                  durationMinutes:
+                    typeof child.timing?.durationMinutes === "number"
+                      ? child.timing.durationMinutes
+                      : null,
+                  jobs: timingJobs,
+                },
+                url: boundedString(child.url, MAX_URL_LENGTH),
+                workflow: boundedString(child.workflow, MAX_LABEL_LENGTH),
+                workflowRef: boundedString(child.workflowRef, MAX_LABEL_LENGTH),
+                workflowSha: boundedString(child.workflowSha, MAX_LABEL_LENGTH),
+              },
+            ];
+          }),
+        )
+      : {};
+  return {
+    ...payload,
+    activeRunIds,
+    blockers,
+    children,
+    errors,
+    parentRunAttempt: positiveInteger(payload.parentRunAttempt),
+    sourceParentRunAttempt: positiveInteger(payload.sourceParentRunAttempt),
+  };
+}
+
+export function releasePlanGateFailures(gates) {
+  return gates
+    .filter((gate) => gate.required && gate.result !== "success")
+    .map((gate) => ({
+      child: "<parent>",
+      conclusion: stringValue(gate.result, "missing"),
+      job: stringValue(gate.name, "parent gate"),
+      kind: "parent_gate_failure",
+      message: `${stringValue(gate.name, "parent gate")} did not succeed`,
+    }));
+}
+
+function verifyStateChildren(state, executionPlan, label) {
+  const selected = executionPlan.children.filter((entry) => entry.selected);
+  const expectedKeys = selected.map((child) => child.key).toSorted();
+  const actualKeys = Object.keys(state.children).toSorted();
+  if (JSON.stringify(actualKeys) !== JSON.stringify(expectedKeys)) {
+    throw new Error(`${label} child set differs from the immutable execution plan`);
+  }
+  if (
+    state.activeRunIds.length > 0 ||
+    state.cancellation?.requested === true ||
+    (state.cancellation?.cancelledRunIds?.length ?? 0) > 0
+  ) {
+    throw new Error(`${label} claims passed with active or cancelled children`);
+  }
+  const snapshots = selected.map((child) => {
+    if (!child.runId || !child.runAttempt) {
+      throw new Error(`selected release child omitted exact identity: ${child.key}`);
+    }
+    const snapshot = state.children[child.key];
+    if (
+      !snapshot ||
+      snapshot.runId !== child.runId ||
+      snapshot.runAttempt !== child.runAttempt ||
+      snapshot.displayTitle !== child.displayTitle ||
+      snapshot.workflow !== child.workflow ||
+      snapshot.workflowRef !== child.workflowRef ||
+      snapshot.workflowSha !== child.workflowSha
+    ) {
+      throw new Error(`${label} child provenance differs from the immutable plan: ${child.key}`);
+    }
+    if (snapshot.errors.length > 0) {
+      throw new Error(`${label} child contains collector errors: ${child.key}`);
+    }
+    return Object.assign({}, child, snapshot, {
+      jobs: snapshot.timing.jobs.map((job) => ({
+        conclusion: job.conclusion,
+        html_url: job.url,
+        name: job.name,
+        status: job.status,
+        url: job.url,
+      })),
+    });
+  });
+  const recomputed = classifyReleaseSnapshot({
+    children: snapshots,
+    extraBlockers: executionPlan.blockers,
+    extraErrors: executionPlan.errors,
+    localFailures: releasePlanGateFailures(executionPlan.gates),
+    releaseProfile: executionPlan.releaseProfile,
+    workflowRef: executionPlan.workflowRef,
+  });
+  if (
+    state.state !== "passed" ||
+    state.blockers.length > 0 ||
+    state.errors.length > 0 ||
+    recomputed.state !== "passed" ||
+    recomputed.blockers.length > 0 ||
+    recomputed.errors.length > 0
+  ) {
+    throw new Error(`${label} does not satisfy canonical terminal release policy`);
+  }
+}
+
+export function verifyReleaseStateArtifacts(
+  executionPlanPayload,
+  decisionPayload,
+  drainPayload,
+  expected = {},
+) {
+  const executionPlan = validateReleaseExecutionPlanArtifact(executionPlanPayload, expected);
+  const decision = validateReleaseStateArtifact(decisionPayload, expected, "decision");
+  const drain = validateReleaseStateArtifact(drainPayload, expected, "drain");
+  if (
+    decision.executionPlanSha256 !== executionPlan.sha256 ||
+    drain.executionPlanSha256 !== executionPlan.sha256 ||
+    decision.sourceParentRunAttempt !== executionPlan.parentRunAttempt ||
+    drain.sourceParentRunAttempt !== executionPlan.parentRunAttempt
+  ) {
+    throw new Error("release decision and diagnostic drain execution plans differ");
+  }
+  verifyStateChildren(decision, executionPlan, "release decision");
+  verifyStateChildren(drain, executionPlan, "diagnostic drain");
+  return {
+    decision,
+    drain,
+    executionPlan,
+    sourceAttempts: {
+      decision: decision.parentRunAttempt,
+      drain: drain.parentRunAttempt,
+      executionPlan: executionPlan.parentRunAttempt,
+    },
+  };
+}
+
+function newestStateCandidate(candidates, mode, runId, expected) {
+  const prefix = mode === "decision" ? "full-release-decision" : "full-release-diagnostics";
+  const pattern = new RegExp(`^${prefix}-${runId}-([1-9][0-9]*)$`, "u");
+  const maxParentRunAttempt =
+    expected.maxParentRunAttempt === undefined
+      ? Number.POSITIVE_INFINITY
+      : Number(expected.maxParentRunAttempt);
+  const sorted = candidates
+    .map((candidate) => {
+      const match = pattern.exec(String(candidate.name ?? ""));
+      return match ? { ...candidate, attempt: Number(match[1]) } : undefined;
+    })
+    .filter(Boolean)
+    .filter((candidate) => candidate.attempt <= maxParentRunAttempt)
+    .toSorted((left, right) => right.attempt - left.attempt);
+  const newest = sorted[0];
+  if (!newest) {
+    throw new Error(`no ${mode} artifact exists at or before the current parent attempt`);
+  }
+  const payload = validateReleaseStateArtifact(newest.payload, expected, mode);
+  if (payload.parentRunAttempt !== newest.attempt) {
+    throw new Error(`${mode} artifact name and source attempt differ`);
+  }
+  return payload;
+}
+
+export function selectReleaseStateArtifacts(
+  executionPlanPayload,
+  decisionCandidates,
+  drainCandidates,
+  expected = {},
+) {
+  const executionPlan = validateReleaseExecutionPlanArtifact(executionPlanPayload, expected);
+  const selectionExpected = {
+    ...expected,
+    parentRunAttempt: undefined,
+  };
+  const decision = newestStateCandidate(
+    decisionCandidates,
+    "decision",
+    executionPlan.parentRunId,
+    selectionExpected,
+  );
+  const drain = newestStateCandidate(
+    drainCandidates,
+    "drain",
+    executionPlan.parentRunId,
+    selectionExpected,
+  );
+  return verifyReleaseStateArtifacts(executionPlan, decision, drain, selectionExpected);
+}
+
+function issueSummary(prefix, issue) {
+  const label =
+    issue.job || issue.message || issue.child || issue.kind || `${prefix.toLowerCase()} detail`;
+  const result = issue.conclusion ? ` (${issue.conclusion})` : "";
+  const url = issue.url ? ` ${issue.url}` : "";
+  return `- ${prefix}: ${label}${result}${url}`;
+}
+
+function releaseStateDetailLines(payload, maxItems = MAX_SUMMARY_ISSUES) {
+  const normalizedMax = Math.max(1, Math.min(maxItems || MAX_SUMMARY_ISSUES, 10));
+  const lines = [];
+  for (const blocker of payload.blockers.slice(0, normalizedMax)) {
+    lines.push(issueSummary("Blocker", blocker));
+  }
+  for (const error of payload.errors.slice(0, normalizedMax)) {
+    lines.push(issueSummary("Collector error", error));
+  }
+  const omitted =
+    Math.max(0, payload.blockers.length - normalizedMax) +
+    Math.max(0, payload.errors.length - normalizedMax);
+  if (omitted > 0) {
+    lines.push(`- ${omitted} additional blocker/error item(s) omitted`);
+  }
+  return lines;
+}
+
+export function formatReleaseStateOutcome(payload) {
+  const lines = [`Full Release Validation state: ${payload.state}`];
+  lines.push(...releaseStateDetailLines(payload));
+  if (payload.state === "blocked_diagnostics_running") {
+    lines.push(
+      "Diagnostic Drain is still collecting terminal evidence; diagnose now, retry later.",
+    );
+  } else if (payload.state === "orchestration_error") {
+    lines.push("Recover the collector against the same exact child runs; do not redispatch tests.");
+  } else if (payload.state === "cancelled_with_children") {
+    lines.push("The collector stopped while exact child runs remained active.");
+  }
+  return lines.join("\n");
+}
+
+export function affectedActiveRunIds(children, blockers, cancelledRunIds = new Set()) {
+  const affected = new Set(
+    blockers.map((blocker) => String(blocker.runId ?? "")).filter((runId) => runId),
+  );
+  return children
+    .filter(
+      (child) =>
+        child.status !== "completed" &&
+        affected.has(String(child.runId)) &&
+        !cancelledRunIds.has(String(child.runId)),
+    )
+    .map((child) => String(child.runId));
+}
diff --git a/scripts/full-release-validation-state.d.mts b/scripts/full-release-validation-state.d.mts
new file mode 100644
index 000000000000..d8df995645f0
--- /dev/null
+++ b/scripts/full-release-validation-state.d.mts
@@ -0,0 +1,15 @@
+export * from "./full-release-validation-policy.mjs";
+export function validateChildBinding(
+  child: Record<string, unknown>,
+  run: Record<string, unknown>,
+  jobs: Record<string, unknown>[],
+): Record<string, unknown>;
+export function parsePlanInputs(value: string): Record<string, unknown>;
+export function hydrateReusedPlan(
+  plan: Record<string, unknown>[],
+  evidence: Record<string, unknown>,
+): Record<string, unknown>[];
+export function formatReleaseStateHeartbeat(
+  mode: string,
+  decision: Record<string, unknown>,
+): string;
diff --git a/scripts/full-release-validation-state.mjs b/scripts/full-release-validation-state.mjs
new file mode 100644
index 000000000000..4dabbcf15a35
--- /dev/null
+++ b/scripts/full-release-validation-state.mjs
@@ -0,0 +1,928 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import {
+  affectedActiveRunIds,
+  buildReleaseExecutionPlan,
+  buildReleaseExecutionPlanArtifact,
+  buildReleaseStateArtifact,
+  classifyReleaseGhTransportError,
+  classifyReleaseSnapshot,
+  formatReleaseStateOutcome,
+  releasePlanGateFailures,
+  selectReleaseStateArtifacts,
+  validateReleaseExecutionPlanArtifact,
+  verifyReleaseStateArtifacts,
+} from "./full-release-validation-policy.mjs";
+
+export * from "./full-release-validation-policy.mjs";
+
+const execFileAsync = promisify(execFile);
+const RELEASE_SUMMARY_PATH =
+  process.env.OPENCLAW_RELEASE_CI_SUMMARY_VALIDATOR ??
+  fileURLToPath(new URL("./release-ci-summary.mjs", import.meta.url));
+const API_ERROR_PATTERN =
+  /HTTP [45][0-9][0-9]|API|Bad credentials|rate limit|network|connection|timeout|ETIMEDOUT|ECONNRESET|EAI_AGAIN/u;
+const DEFAULT_POLL_INTERVAL_MS = 60_000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 5 * 60_000;
+const GH_TIMEOUT_MS = 60_000;
+
+function stringValue(value, fallback = "") {
+  return typeof value === "string" ? value : fallback;
+}
+
+function requiredString(value, label) {
+  const normalized = stringValue(value).trim();
+  if (!normalized) {
+    throw new Error(`${label} is required`);
+  }
+  return normalized;
+}
+
+function positiveInteger(value, label) {
+  const normalized = Number(value);
+  if (!Number.isSafeInteger(normalized) || normalized < 1) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return normalized;
+}
+
+async function abortableSleep(milliseconds, signal) {
+  let abortError;
+  await new Promise((resolve) => {
+    const timer = setTimeout(resolve, milliseconds);
+    const abort = () => {
+      clearTimeout(timer);
+      abortError = signal?.reason instanceof Error ? signal.reason : new Error("operation aborted");
+      resolve();
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+  if (abortError instanceof Error) {
+    throw new Error(abortError.message, { cause: abortError });
+  }
+}
+
+async function runGh(args, options = {}) {
+  const attempts = options.attempts ?? 6;
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      const result = await execFileAsync("gh", args, {
+        encoding: "utf8",
+        env: process.env,
+        killSignal: "SIGKILL",
+        maxBuffer: 64 * 1024 * 1024,
+        signal: options.signal,
+        timeout: GH_TIMEOUT_MS,
+      });
+      return result.stdout;
+    } catch (error) {
+      lastError = error;
+      if (options.signal?.aborted) {
+        throw options.signal.reason ?? error;
+      }
+      if (attempt === attempts || classifyReleaseGhTransportError(error) !== "transient") {
+        throw error;
+      }
+      await abortableSleep(Math.min(attempt * 10_000, 60_000), options.signal);
+    }
+  }
+  throw lastError;
+}
+
+async function githubJson(path, signal) {
+  return JSON.parse(
+    await runGh(["api", `repos/${process.env.GITHUB_REPOSITORY}/${path}`], { signal }),
+  );
+}
+
+async function githubJobs(runId, signal) {
+  return (
+    await runGh(
+      [
+        "api",
+        "--paginate",
+        `repos/${process.env.GITHUB_REPOSITORY}/actions/runs/${runId}/jobs?per_page=100`,
+        "--jq",
+        ".jobs[] | @json",
+      ],
+      { signal },
+    )
+  )
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+function issue(kind, child, message, extra = {}) {
+  return {
+    child: child.key,
+    kind,
+    message,
+    runId: stringValue(child.runId),
+    url: stringValue(child.url),
+    ...extra,
+  };
+}
+
+export function validateChildBinding(child, run, jobs) {
+  const errors = [];
+  const path = stringValue(run.path).split("@", 1)[0];
+  if (String(run.id) !== String(child.runId)) {
+    errors.push(issue("provenance_mismatch", child, `${child.key} run ID changed`));
+  }
+  if (run.event !== "workflow_dispatch") {
+    errors.push(issue("provenance_mismatch", child, `${child.key} event changed`));
+  }
+  if (path !== `.github/workflows/${child.workflow}`) {
+    errors.push(issue("provenance_mismatch", child, `${child.key} workflow path changed`));
+  }
+  if (run.display_title !== child.displayTitle) {
+    errors.push(issue("provenance_mismatch", child, `${child.key} display title changed`));
+  }
+  if (run.head_branch !== child.workflowRef) {
+    errors.push(issue("provenance_mismatch", child, `${child.key} workflow ref changed`));
+  }
+  if (run.head_sha !== child.workflowSha) {
+    errors.push(issue("provenance_mismatch", child, `${child.key} tooling SHA changed`));
+  }
+  if (Number(run.run_attempt) !== Number(child.runAttempt)) {
+    errors.push(issue("provenance_mismatch", child, `${child.key} run attempt changed`));
+  }
+  return {
+    ...child,
+    conclusion: stringValue(run.conclusion),
+    createdAt: stringValue(run.created_at),
+    errors,
+    jobs,
+    runAttempt: Number(run.run_attempt),
+    runId: String(run.id),
+    status: stringValue(run.status),
+    updatedAt: stringValue(run.updated_at),
+    url: stringValue(run.html_url, child.url),
+    workflowRef: stringValue(run.head_branch),
+    workflowSha: stringValue(run.head_sha),
+  };
+}
+
+async function readChild(child, previous, signal) {
+  if (!child.selected) {
+    return { ...child, errors: [], jobs: [], status: "skipped" };
+  }
+  if (!child.runId || !child.runAttempt) {
+    return {
+      ...child,
+      errors: [issue("dispatch_missing", child, `${child.key} omitted its exact run identity`)],
+      jobs: [],
+      status: "missing",
+    };
+  }
+  try {
+    const run = await githubJson(`actions/runs/${child.runId}`, signal);
+    return validateChildBinding(child, run, await githubJobs(child.runId, signal));
+  } catch (error) {
+    return {
+      ...child,
+      conclusion: stringValue(previous?.conclusion),
+      createdAt: stringValue(previous?.createdAt),
+      errors: [
+        ...(previous?.errors ?? []).filter((entry) => entry.kind === "provenance_mismatch"),
+        issue(
+          "api_error",
+          child,
+          `${child.key} GitHub read failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        ),
+      ],
+      jobs: previous?.jobs ?? [],
+      status: stringValue(previous?.status, "unknown"),
+      updatedAt: stringValue(previous?.updatedAt),
+    };
+  }
+}
+
+export function parsePlanInputs(value) {
+  const parsed = JSON.parse(requiredString(value, "plan inputs JSON"));
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("plan inputs JSON must be an object");
+  }
+  return parsed;
+}
+
+export function hydrateReusedPlan(plan, evidence) {
+  const byRole = new Map((evidence.children ?? []).map((child) => [child.role, child]));
+  return plan.map((child) => {
+    if (!child.selected) {
+      return child;
+    }
+    const reused = byRole.get(child.key);
+    if (!reused) {
+      return child;
+    }
+    return {
+      ...child,
+      displayTitle: reused.displayTitle,
+      result: "success",
+      runAttempt: reused.runAttempt,
+      runId: reused.runId,
+      url: reused.url,
+      workflowRef: reused.headBranch,
+      workflowSha: reused.workflowSha,
+    };
+  });
+}
+
+function changedPathsValue(value) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  try {
+    const parsed = JSON.parse(stringValue(value, "[]"));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalJson);
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .toSorted(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, canonicalJson(entry)]),
+    );
+  }
+  return value;
+}
+
+async function validateReuse(plan, planInputs, signal) {
+  if (!(planInputs.evidenceReuse === true || planInputs.evidenceReuse === "true")) {
+    return { blockers: [], children: plan, errors: [] };
+  }
+  try {
+    const args = [
+      RELEASE_SUMMARY_PATH,
+      "--validate-run",
+      requiredString(planInputs.evidenceRunId, "evidence selected run ID"),
+      "--repo",
+      requiredString(process.env.GITHUB_REPOSITORY, "GitHub repository"),
+      "--trusted-workflow-ref",
+      requiredString(planInputs.trustedWorkflow?.ref, "trusted workflow ref"),
+      "--trusted-workflow-full-ref",
+      requiredString(planInputs.trustedWorkflow?.fullRef, "trusted workflow full ref"),
+      "--trusted-workflow-sha",
+      requiredString(planInputs.trustedWorkflow?.sha, "trusted workflow SHA"),
+      "--verifier-source-sha",
+      requiredString(planInputs.workflowSha, "workflow SHA"),
+      "--verifier-source-file",
+      RELEASE_SUMMARY_PATH,
+      "--expected-target-sha",
+      requiredString(process.env.TARGET_SHA, "target SHA"),
+      "--expected-evidence-policy",
+      requiredString(planInputs.evidencePolicy, "evidence policy"),
+      "--expected-evidence-sha",
+      requiredString(planInputs.evidenceSha, "evidence SHA"),
+      "--expected-root-run-id",
+      requiredString(planInputs.evidenceRootRunId, "evidence root run ID"),
+      "--expected-selected-run-id",
+      requiredString(planInputs.evidenceRunId, "evidence selected run ID"),
+      "--expected-changed-paths-json",
+      JSON.stringify(changedPathsValue(planInputs.evidenceChangedPaths)),
+      "--json",
+    ];
+    const result = await execFileAsync(process.execPath, args, {
+      encoding: "utf8",
+      env: process.env,
+      killSignal: "SIGKILL",
+      maxBuffer: 64 * 1024 * 1024,
+      signal,
+      timeout: GH_TIMEOUT_MS * 6,
+    });
+    const evidence = JSON.parse(result.stdout);
+    if (
+      evidence.releaseProfile !== process.env.RELEASE_PROFILE ||
+      evidence.rerunGroup !== process.env.RERUN_GROUP ||
+      !evidence.manifest ||
+      typeof evidence.manifest !== "object" ||
+      Array.isArray(evidence.manifest)
+    ) {
+      throw new Error("reused release evidence no longer matches the requested validation");
+    }
+    return {
+      blockers: [],
+      children: hydrateReusedPlan(plan, evidence),
+      errors: [],
+      sourceManifest: canonicalJson(evidence.manifest),
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const entry = {
+      child: "<evidence>",
+      kind: API_ERROR_PATTERN.test(message) ? "api_error" : "reused_evidence_invalid",
+      message,
+      runId: stringValue(planInputs.evidenceRunId),
+      url: stringValue(planInputs.evidenceRunUrl),
+    };
+    return API_ERROR_PATTERN.test(message)
+      ? { blockers: [], children: plan, errors: [entry] }
+      : { blockers: [entry], children: plan, errors: [] };
+  }
+}
+
+function writeArtifact(path, payload) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function writeResult(path, payload) {
+  writeArtifact(path, payload);
+  if (process.env.GITHUB_OUTPUT) {
+    appendFileSync(process.env.GITHUB_OUTPUT, `state=${payload.state}\n`);
+    for (const [key, child] of Object.entries(payload.children ?? {})) {
+      appendFileSync(process.env.GITHUB_OUTPUT, `${key}_conclusion=${child.conclusion ?? ""}\n`);
+    }
+  }
+}
+
+function writeExecutionPlan(path, payload) {
+  writeArtifact(path, payload);
+  if (process.env.GITHUB_OUTPUT) {
+    appendFileSync(process.env.GITHUB_OUTPUT, `sha256=${payload.sha256}\n`);
+    appendFileSync(
+      process.env.GITHUB_OUTPUT,
+      `source_parent_attempt=${payload.parentRunAttempt}\n`,
+    );
+  }
+}
+
+function appendSummary(mode, payload) {
+  if (!process.env.GITHUB_STEP_SUMMARY) {
+    return;
+  }
+  appendFileSync(
+    process.env.GITHUB_STEP_SUMMARY,
+    `## ${mode === "decision" ? "Release Decision" : "Diagnostic Drain"}\n\n${formatReleaseStateOutcome(payload)}\n`,
+  );
+}
+
+export function formatReleaseStateHeartbeat(mode, decision) {
+  return `${mode} heartbeat: state=${decision.state} active=${decision.activeRunIds.length} blockers=${decision.blockers.length} errors=${decision.errors.length}`;
+}
+
+async function cancelAffectedChildren(children, blockers, cancelledRunIds, signal) {
+  const errors = [];
+  for (const runId of affectedActiveRunIds(children, blockers, cancelledRunIds)) {
+    const child = children.find((entry) => String(entry.runId) === runId);
+    try {
+      await runGh(["run", "cancel", runId], { attempts: 1, signal });
+      cancelledRunIds.add(runId);
+    } catch (error) {
+      errors.push(
+        issue(
+          "api_error",
+          child ?? { key: "<child>", runId },
+          `exact child cancellation failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        ),
+      );
+    }
+  }
+  return errors;
+}
+
+function readArtifact(path, label) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `${label} artifact is unreadable: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+}
+
+function verifyMode() {
+  const expected = {
+    maxParentRunAttempt: positiveInteger(process.env.GITHUB_RUN_ATTEMPT, "parent run attempt"),
+    parentRunId: requiredString(process.env.GITHUB_RUN_ID, "parent run ID"),
+    releaseProfile: requiredString(process.env.RELEASE_PROFILE, "release profile"),
+    rerunGroup: requiredString(process.env.RERUN_GROUP, "rerun group"),
+    targetSha: requiredString(process.env.TARGET_SHA, "target SHA"),
+    workflowRef: requiredString(process.env.GITHUB_REF_NAME, "workflow ref"),
+    workflowSha: requiredString(process.env.GITHUB_SHA, "workflow SHA"),
+  };
+  const verified = verifyReleaseStateArtifacts(
+    readArtifact(
+      requiredString(process.env.RELEASE_EXECUTION_PLAN_PATH, "execution plan path"),
+      "execution plan",
+    ),
+    readArtifact(requiredString(process.env.RELEASE_DECISION_PATH, "decision path"), "decision"),
+    readArtifact(requiredString(process.env.DIAGNOSTIC_DRAIN_PATH, "drain path"), "drain"),
+    expected,
+  );
+  appendSummary("decision", verified.decision);
+  appendSummary("drain", verified.drain);
+}
+
+function planExpected() {
+  return {
+    parentRunId: requiredString(process.env.GITHUB_RUN_ID, "parent run ID"),
+    releaseProfile: requiredString(process.env.RELEASE_PROFILE, "release profile"),
+    rerunGroup: requiredString(process.env.RERUN_GROUP, "rerun group"),
+    targetSha: stringValue(process.env.TARGET_SHA),
+    workflowSha: requiredString(process.env.GITHUB_SHA, "workflow SHA"),
+    workflowRef: requiredString(process.env.GITHUB_REF_NAME, "workflow ref"),
+  };
+}
+
+function evidenceReuseFromInputs(planInputs, sourceManifest = {}) {
+  return {
+    changedPaths: changedPathsValue(planInputs.evidenceChangedPaths),
+    evidenceSha: stringValue(planInputs.evidenceSha),
+    policy: stringValue(planInputs.evidencePolicy),
+    requested: planInputs.evidenceReuse === true || planInputs.evidenceReuse === "true",
+    rootRunId: stringValue(planInputs.evidenceRootRunId),
+    runUrl: stringValue(planInputs.evidenceRunUrl),
+    selectedRunId: stringValue(planInputs.evidenceRunId),
+    sourceManifest,
+  };
+}
+
+function trustedWorkflowFromInputs(planInputs) {
+  return planInputs.trustedWorkflow;
+}
+
+async function planMode() {
+  const outputPath = requiredString(
+    process.env.FULL_RELEASE_EXECUTION_PLAN_PATH,
+    "execution plan output path",
+  );
+  const expected = planExpected();
+  const currentAttempt = positiveInteger(process.env.GITHUB_RUN_ATTEMPT, "parent run attempt");
+
+  if (process.env.FULL_RELEASE_RESTORE_PLAN === "true") {
+    const restored = validateReleaseExecutionPlanArtifact(
+      readArtifact(outputPath, "execution plan"),
+      expected,
+    );
+    writeExecutionPlan(outputPath, restored);
+    return;
+  }
+  if (currentAttempt !== 1) {
+    throw new Error("collector retry omitted the immutable attempt-one execution plan");
+  }
+
+  const planInputs = parsePlanInputs(process.env.FULL_RELEASE_PLAN_INPUTS_JSON);
+  const built = buildReleaseExecutionPlan(planInputs);
+  const abortController = new AbortController();
+  let finished = false;
+  let plan = buildReleaseExecutionPlanArtifact({
+    children: built.children,
+    evidenceReuse: evidenceReuseFromInputs(planInputs),
+    expected: { ...expected, parentRunAttempt: currentAttempt },
+    gates: built.gates,
+    releaseProfile: expected.releaseProfile,
+    rerunGroup: expected.rerunGroup,
+    trustedWorkflow: trustedWorkflowFromInputs(planInputs),
+  });
+  const stop = () => {
+    if (finished) {
+      return;
+    }
+    abortController.abort(new Error("execution plan collection cancelled"));
+    plan = buildReleaseExecutionPlanArtifact({
+      blockers: plan.blockers,
+      children: plan.children,
+      errors: [
+        ...plan.errors,
+        {
+          child: "<collector>",
+          kind: "collector_cancelled",
+          message: "execution plan collector received a termination signal",
+        },
+      ],
+      evidenceReuse: plan.evidenceReuse,
+      expected: { ...expected, parentRunAttempt: currentAttempt },
+      gates: plan.gates,
+      releaseProfile: expected.releaseProfile,
+      rerunGroup: expected.rerunGroup,
+      trustedWorkflow: plan.trustedWorkflow,
+    });
+    writeExecutionPlan(outputPath, plan);
+    finished = true;
+    process.exit(1);
+  };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+
+  const reuse = await validateReuse(built.children, planInputs, abortController.signal);
+  if (finished) {
+    return;
+  }
+  plan = buildReleaseExecutionPlanArtifact({
+    blockers: reuse.blockers,
+    children: reuse.children,
+    errors: reuse.errors,
+    evidenceReuse: evidenceReuseFromInputs(planInputs, reuse.sourceManifest),
+    expected: { ...expected, parentRunAttempt: currentAttempt },
+    gates: built.gates,
+    releaseProfile: expected.releaseProfile,
+    rerunGroup: expected.rerunGroup,
+    trustedWorkflow: trustedWorkflowFromInputs(planInputs),
+  });
+  writeExecutionPlan(outputPath, plan);
+  finished = true;
+  if ((reuse.blockers?.length ?? 0) > 0 || (reuse.errors?.length ?? 0) > 0) {
+    throw new Error("release execution plan could not bind reusable evidence");
+  }
+}
+
+async function collectMode(mode) {
+  const expected = {
+    parentRunAttempt: positiveInteger(process.env.GITHUB_RUN_ATTEMPT, "parent run attempt"),
+    parentRunId: requiredString(process.env.GITHUB_RUN_ID, "parent run ID"),
+    targetSha: stringValue(process.env.TARGET_SHA),
+    workflowRef: requiredString(process.env.GITHUB_REF_NAME, "workflow ref"),
+    workflowSha: requiredString(process.env.GITHUB_SHA, "workflow SHA"),
+  };
+  const releaseProfile = requiredString(process.env.RELEASE_PROFILE, "release profile");
+  const rerunGroup = requiredString(process.env.RERUN_GROUP, "rerun group");
+  const outputPath = requiredString(process.env.FULL_RELEASE_STATE_PATH, "state output path");
+  const executionPlan = validateReleaseExecutionPlanArtifact(
+    readArtifact(
+      requiredString(process.env.FULL_RELEASE_EXECUTION_PLAN_PATH, "execution plan path"),
+      "execution plan",
+    ),
+    {
+      parentRunId: expected.parentRunId,
+      releaseProfile,
+      rerunGroup,
+      targetSha: expected.targetSha,
+      workflowSha: expected.workflowSha,
+    },
+  );
+  const plan = executionPlan.children;
+  const gateFailures = releasePlanGateFailures(executionPlan.gates);
+  const failFast = mode === "decision" && process.env.FAIL_FAST === "true";
+  const pollIntervalMs =
+    Number(process.env.FULL_RELEASE_POLL_INTERVAL_MS) || DEFAULT_POLL_INTERVAL_MS;
+  const heartbeatIntervalMs =
+    Number(process.env.FULL_RELEASE_HEARTBEAT_INTERVAL_MS) || DEFAULT_HEARTBEAT_INTERVAL_MS;
+  const cancelledRunIds = new Set();
+  let snapshots = plan.map((child) => ({
+    ...child,
+    errors: [],
+    jobs: [],
+    status: child.selected && child.runId ? "queued" : child.selected ? "missing" : "skipped",
+  }));
+  let finished = false;
+  const abortController = new AbortController();
+  let decisionReuse = { blockers: [], children: plan, errors: [] };
+
+  const writePayload = (decision, cancellation = {}) => {
+    const payload = buildReleaseStateArtifact({
+      cancellation,
+      children: snapshots,
+      decision,
+      executionPlan,
+      expected,
+      mode,
+      releaseProfile,
+      rerunGroup,
+    });
+    writeResult(outputPath, payload);
+    appendSummary(mode, payload);
+    return payload;
+  };
+  const stop = () => {
+    if (finished) {
+      return;
+    }
+    abortController.abort(new Error(`${mode} collector cancelled`));
+    const decision = classifyReleaseSnapshot({
+      cancelled: true,
+      children: snapshots,
+      extraBlockers: executionPlan.blockers,
+      extraErrors: [
+        ...executionPlan.errors,
+        {
+          child: "<collector>",
+          kind: "collector_cancelled",
+          message: `${mode} collector received a termination signal`,
+        },
+      ],
+      localFailures: gateFailures,
+      releaseProfile,
+      workflowRef: expected.workflowRef,
+    });
+    writePayload(decision, { cancelledRunIds, requested: true });
+    finished = true;
+    process.exit(1);
+  };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+
+  if (mode === "decision" && executionPlan.evidenceReuse.requested) {
+    decisionReuse = await validateReuse(
+      plan,
+      {
+        evidenceChangedPaths: executionPlan.evidenceReuse.changedPaths,
+        evidencePolicy: executionPlan.evidenceReuse.policy,
+        evidenceReuse: true,
+        evidenceRunId: executionPlan.evidenceReuse.selectedRunId,
+        evidenceRootRunId: executionPlan.evidenceReuse.rootRunId,
+        evidenceRunUrl: executionPlan.evidenceReuse.runUrl,
+        evidenceSha: executionPlan.evidenceReuse.evidenceSha,
+        trustedWorkflow: executionPlan.trustedWorkflow,
+        workflowSha: executionPlan.workflowSha,
+      },
+      abortController.signal,
+    );
+    const exactPlan = JSON.stringify(
+      plan.map(({ key, runAttempt, runId }) => ({ key, runAttempt, runId })),
+    );
+    const revalidatedPlan = JSON.stringify(
+      decisionReuse.children.map(({ key, runAttempt, runId }) => ({ key, runAttempt, runId })),
+    );
+    if (exactPlan !== revalidatedPlan) {
+      decisionReuse = {
+        ...decisionReuse,
+        blockers: [
+          ...decisionReuse.blockers,
+          {
+            child: "<evidence>",
+            kind: "provenance_mismatch",
+            message: "revalidated evidence child identities differ from the immutable plan",
+            runId: executionPlan.evidenceReuse.rootRunId,
+            url: executionPlan.evidenceReuse.runUrl,
+          },
+        ],
+      };
+    }
+    if (
+      JSON.stringify(canonicalJson(decisionReuse.sourceManifest)) !==
+      JSON.stringify(canonicalJson(executionPlan.evidenceReuse.sourceManifest))
+    ) {
+      decisionReuse = {
+        ...decisionReuse,
+        blockers: [
+          ...decisionReuse.blockers,
+          {
+            child: "<evidence>",
+            kind: "provenance_mismatch",
+            message: "revalidated evidence source manifest differs from the immutable plan",
+            runId: executionPlan.evidenceReuse.rootRunId,
+            url: executionPlan.evidenceReuse.runUrl,
+          },
+        ],
+      };
+    }
+  }
+
+  let nextHeartbeat = 0;
+  while (!finished) {
+    snapshots = await Promise.all(
+      plan.map((child, index) => readChild(child, snapshots[index], abortController.signal)),
+    );
+    let decision = classifyReleaseSnapshot({
+      children: snapshots,
+      extraBlockers: [...executionPlan.blockers, ...decisionReuse.blockers],
+      extraErrors: [...executionPlan.errors, ...decisionReuse.errors],
+      localFailures: gateFailures,
+      releaseProfile,
+      workflowRef: expected.workflowRef,
+    });
+    if (Date.now() >= nextHeartbeat) {
+      console.log(formatReleaseStateHeartbeat(mode, decision));
+      nextHeartbeat = Date.now() + heartbeatIntervalMs;
+    }
+    if (failFast && decision.blockers.length > 0) {
+      const cancellationErrors = await cancelAffectedChildren(
+        snapshots,
+        decision.blockers,
+        cancelledRunIds,
+        abortController.signal,
+      );
+      if (cancellationErrors.length > 0) {
+        decision = classifyReleaseSnapshot({
+          children: snapshots,
+          extraBlockers: [
+            ...executionPlan.blockers,
+            ...decisionReuse.blockers,
+            ...decision.blockers,
+          ],
+          extraErrors: [...executionPlan.errors, ...decisionReuse.errors, ...cancellationErrors],
+          localFailures: gateFailures,
+          releaseProfile,
+          workflowRef: expected.workflowRef,
+        });
+      }
+    }
+    const done =
+      mode === "decision"
+        ? decision.state !== "qualifying"
+        : decision.state === "orchestration_error" ||
+          (decision.state !== "qualifying" && decision.activeRunIds.length === 0);
+    if (done) {
+      const payload = writePayload(decision, { cancelledRunIds, requested: false });
+      finished = true;
+      process.exitCode =
+        payload.state === "passed" ? 0 : payload.state === "orchestration_error" ? 2 : 1;
+      return;
+    }
+    await abortableSleep(pollIntervalMs, abortController.signal);
+  }
+}
+
+function readStateCandidates(root, prefix, runId, maxParentRunAttempt, filename) {
+  const pattern = new RegExp(`^${prefix}-${runId}-([1-9][0-9]*)$`, "u");
+  const candidates = readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const match = pattern.exec(entry.name);
+      return match ? { attempt: Number(match[1]), name: entry.name } : undefined;
+    })
+    .filter(Boolean)
+    .filter((entry) => entry.attempt <= maxParentRunAttempt)
+    .map((entry) => {
+      const payload = readArtifact(join(root, entry.name, filename), entry.name);
+      if (Number(payload.parentRunAttempt) !== entry.attempt) {
+        throw new Error(`${entry.name} payload attempt differs from its artifact name`);
+      }
+      return { name: entry.name, payload };
+    });
+  const directPath = join(root, filename);
+  if (existsSync(directPath)) {
+    const payload = readArtifact(directPath, filename);
+    const attempt = positiveInteger(payload.parentRunAttempt, `${filename} parent run attempt`);
+    if (attempt <= maxParentRunAttempt) {
+      candidates.push({ name: `${prefix}-${runId}-${attempt}`, payload });
+    }
+  }
+  return candidates;
+}
+
+async function validateManifestMode() {
+  const manifestPath = requiredString(
+    process.env.RELEASE_VALIDATION_MANIFEST_PATH,
+    "release validation manifest path",
+  );
+  const executionPlan = validateReleaseExecutionPlanArtifact(
+    readArtifact(
+      requiredString(process.env.RELEASE_EXECUTION_PLAN_PATH, "execution plan path"),
+      "execution plan",
+    ),
+    {
+      parentRunId: requiredString(process.env.GITHUB_RUN_ID, "parent run ID"),
+      releaseProfile: requiredString(process.env.RELEASE_PROFILE, "release profile"),
+      rerunGroup: requiredString(process.env.RERUN_GROUP, "rerun group"),
+      targetSha: requiredString(process.env.TARGET_SHA, "target SHA"),
+      workflowRef: requiredString(process.env.GITHUB_REF_NAME, "workflow ref"),
+      workflowSha: requiredString(process.env.GITHUB_SHA, "workflow SHA"),
+    },
+  );
+  const rawManifest = readArtifact(manifestPath, "release validation manifest");
+  const { validateParentManifest } = await import("./release-ci-summary.mjs");
+  const manifest = validateParentManifest(rawManifest, {
+    runAttempt: positiveInteger(process.env.GITHUB_RUN_ATTEMPT, "parent run attempt"),
+    runId: executionPlan.parentRunId,
+    workflowRef: executionPlan.workflowRef,
+    workflowSha: executionPlan.workflowSha,
+  });
+  const expectedChildRunIds = Object.fromEntries(
+    ["normalCi", "npmTelegram", "pluginPrerelease", "productPerformance", "releaseChecks"].map(
+      (key) => {
+        const child = executionPlan.children.find((entry) => entry.key === key);
+        return [key, child?.selected ? stringValue(child.runId) : ""];
+      },
+    ),
+  );
+  const expectedEvidenceReuse = executionPlan.evidenceReuse.requested
+    ? {
+        changedPaths: executionPlan.evidenceReuse.changedPaths,
+        evidenceSha: executionPlan.evidenceReuse.evidenceSha,
+        policy: executionPlan.evidenceReuse.policy,
+        runId: executionPlan.evidenceReuse.rootRunId,
+        selectedRunId: executionPlan.evidenceReuse.selectedRunId,
+      }
+    : undefined;
+  if (
+    manifest.targetSha !== executionPlan.targetSha ||
+    manifest.releaseProfile !== executionPlan.releaseProfile ||
+    manifest.rerunGroup !== executionPlan.rerunGroup ||
+    JSON.stringify(canonicalJson(manifest.childRunIds)) !==
+      JSON.stringify(canonicalJson(expectedChildRunIds)) ||
+    JSON.stringify(canonicalJson(manifest.evidenceReuse)) !==
+      JSON.stringify(canonicalJson(expectedEvidenceReuse)) ||
+    rawManifest.executionPlanSha256 !== executionPlan.sha256 ||
+    Number(rawManifest.sourceParentRunAttempt) !== executionPlan.parentRunAttempt
+  ) {
+    throw new Error("release validation manifest differs from the immutable execution plan");
+  }
+}
+
+function selectMode() {
+  const expected = {
+    maxParentRunAttempt: positiveInteger(
+      process.env.GITHUB_RUN_ATTEMPT,
+      "current parent run attempt",
+    ),
+    parentRunId: requiredString(process.env.GITHUB_RUN_ID, "parent run ID"),
+    releaseProfile: requiredString(process.env.RELEASE_PROFILE, "release profile"),
+    rerunGroup: requiredString(process.env.RERUN_GROUP, "rerun group"),
+    targetSha: requiredString(process.env.TARGET_SHA, "target SHA"),
+    workflowRef: requiredString(process.env.GITHUB_REF_NAME, "workflow ref"),
+    workflowSha: requiredString(process.env.GITHUB_SHA, "workflow SHA"),
+  };
+  const selected = selectReleaseStateArtifacts(
+    readArtifact(
+      requiredString(process.env.RELEASE_EXECUTION_PLAN_PATH, "execution plan path"),
+      "execution plan",
+    ),
+    readStateCandidates(
+      requiredString(process.env.RELEASE_DECISION_ATTEMPTS_PATH, "decision attempts path"),
+      "full-release-decision",
+      expected.parentRunId,
+      expected.maxParentRunAttempt,
+      "full-release-decision.json",
+    ),
+    readStateCandidates(
+      requiredString(process.env.DIAGNOSTIC_DRAIN_ATTEMPTS_PATH, "drain attempts path"),
+      "full-release-diagnostics",
+      expected.parentRunId,
+      expected.maxParentRunAttempt,
+      "full-release-diagnostic-manifest.json",
+    ),
+    expected,
+  );
+  writeArtifact(
+    requiredString(process.env.RELEASE_DECISION_PATH, "selected decision path"),
+    selected.decision,
+  );
+  writeArtifact(
+    requiredString(process.env.DIAGNOSTIC_DRAIN_PATH, "selected drain path"),
+    selected.drain,
+  );
+  if (process.env.GITHUB_OUTPUT) {
+    appendFileSync(
+      process.env.GITHUB_OUTPUT,
+      `decision_source_attempt=${selected.sourceAttempts.decision}\n`,
+    );
+    appendFileSync(
+      process.env.GITHUB_OUTPUT,
+      `drain_source_attempt=${selected.sourceAttempts.drain}\n`,
+    );
+  }
+}
+
+async function main() {
+  const mode = process.argv[2];
+  if (mode === "plan") {
+    await planMode();
+    return;
+  }
+  if (mode === "verify") {
+    verifyMode();
+    return;
+  }
+  if (mode === "select") {
+    selectMode();
+    return;
+  }
+  if (mode === "validate-manifest") {
+    await validateManifestMode();
+    return;
+  }
+  if (!["decision", "drain"].includes(mode)) {
+    throw new Error(
+      "usage: full-release-validation-state.mjs <plan|decision|drain|select|validate-manifest|verify>",
+    );
+  }
+  await collectMode(mode);
+}
+
+if (process.argv[1]?.endsWith("full-release-validation-state.mjs")) {
+  try {
+    await main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(2);
+  }
+}
diff --git a/scripts/release-ci-summary.mjs b/scripts/release-ci-summary.mjs
index 7a32bb9e16fa..caef6f0e9e52 100755
--- a/scripts/release-ci-summary.mjs
+++ b/scripts/release-ci-summary.mjs
@@ -10,6 +10,13 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import {
+  classifyReleaseGhTransportError,
+  formatReleaseStateOutcome,
+  terminalPolicyPass,
+  validateReleaseExecutionPlanArtifact,
+  validateReleaseStateArtifact,
+} from "./full-release-validation-policy.mjs";
 import { execGhRead, plainGhEnv, resolvePlainGhBin } from "./lib/plain-gh.mjs";
 
 const DEFAULT_REPO = process.env.OPENCLAW_RELEASE_REPO || "openclaw/openclaw";
@@ -24,6 +31,8 @@ const MANIFEST_ARTIFACT_ENTRY = "full-release-validation-manifest.json";
 const MAX_MANIFEST_ARTIFACT_ZIP_BYTES = 256 * 1024;
 const MAX_MANIFEST_JSON_BYTES = 128 * 1024;
 const MAX_MANIFEST_ENTRY_LIST_BYTES = 8 * 1024;
+const MAX_RELEASE_STATE_BYTES = 128 * 1024;
+const MAX_EXECUTION_PLAN_BYTES = 128 * 1024;
 // Release evidence lookups run during full release validation, so keep enough
 // headroom for GitHub latency while preventing one stalled read from consuming
 // the workflow budget.
@@ -151,6 +160,51 @@ function downloadArtifactZip(artifactId, destination, repository = DEFAULT_REPO)
   }
 }
 
+function tryDownloadExecutionPlan(runId, repository = DEFAULT_REPO) {
+  const artifactName = `full-release-execution-plan-${runId}`;
+  const downloadDir = mkdtempSync(join(tmpdir(), "openclaw-release-execution-plan-"));
+  try {
+    try {
+      runReleaseCiGh(
+        [
+          "run",
+          "download",
+          String(runId),
+          "--repo",
+          repository,
+          "--name",
+          artifactName,
+          "--dir",
+          downloadDir,
+        ],
+        { stdio: ["ignore", "ignore", "pipe"] },
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (
+        /no valid artifacts found|artifact .* not found|could not find any artifacts/iu.test(
+          message,
+        )
+      ) {
+        return undefined;
+      }
+      throw new Error(`release execution plan artifact read failed: ${message}`, {
+        cause: error,
+      });
+    }
+    const path = join(downloadDir, "full-release-execution-plan.json");
+    if (!statSync(path, { throwIfNoEntry: false })) {
+      throw new Error(`release execution plan artifact ${artifactName} omitted its manifest`);
+    }
+    if (statSync(path).size > MAX_EXECUTION_PLAN_BYTES) {
+      throw new Error(`release execution plan artifact ${artifactName} exceeds the size limit`);
+    }
+    return JSON.parse(readFileSync(path, "utf8"));
+  } finally {
+    rmSync(downloadDir, { force: true, recursive: true });
+  }
+}
+
 function rate() {
   try {
     return jsonGh(["api", "rate_limit"]).resources.core;
@@ -633,6 +687,83 @@ export function validateEvidenceReuseChain(
   return rootManifest.targetSha;
 }
 
+export function validateRequestedEvidenceReuse(
+  currentManifest,
+  selectedManifest,
+  rootManifest,
+  {
+    expectedChangedPaths,
+    expectedEvidencePolicy,
+    expectedEvidenceSha,
+    expectedRootRunId,
+    expectedSelectedRunId,
+    expectedTargetSha,
+  },
+  compareCommits,
+) {
+  if (
+    !Array.isArray(expectedChangedPaths) ||
+    expectedChangedPaths.some(
+      (changedPath) => typeof changedPath !== "string" || changedPath.length === 0,
+    ) ||
+    new Set(expectedChangedPaths).size !== expectedChangedPaths.length
+  ) {
+    throw new Error("expected evidence changed paths are invalid");
+  }
+  const requested = {
+    changedPaths: expectedChangedPaths,
+    evidenceSha: normalizeSha(expectedEvidenceSha, "expected evidence SHA"),
+    policy: String(expectedEvidencePolicy ?? ""),
+    runId: normalizeRequiredRunId(expectedRootRunId, "expected evidence root run ID"),
+    selectedRunId: normalizeRequiredRunId(
+      expectedSelectedRunId,
+      "expected evidence selected run ID",
+    ),
+  };
+  const expectedTarget = normalizeSha(expectedTargetSha, "expected target SHA");
+  const reuse = currentManifest.evidenceReuse;
+  if (!reuse) {
+    if (
+      currentManifest.runId !== requested.selectedRunId ||
+      selectedManifest.runId !== requested.selectedRunId ||
+      rootManifest.runId !== requested.runId
+    ) {
+      throw new Error("reused release evidence no longer matches the requested validation");
+    }
+    validateEvidenceReuseChain(
+      { ...currentManifest, evidenceReuse: requested, targetSha: expectedTarget },
+      selectedManifest,
+      rootManifest,
+      compareCommits,
+    );
+    return;
+  }
+  if (
+    currentManifest.targetSha !== expectedTarget ||
+    selectedManifest.runId !== requested.selectedRunId ||
+    rootManifest.runId !== requested.runId ||
+    rootManifest.targetSha !== requested.evidenceSha ||
+    reuse.evidenceSha !== requested.evidenceSha ||
+    reuse.policy !== requested.policy ||
+    reuse.runId !== requested.runId ||
+    reuse.selectedRunId !== requested.selectedRunId ||
+    JSON.stringify(reuse.changedPaths) !== JSON.stringify(requested.changedPaths)
+  ) {
+    throw new Error("reused release evidence no longer matches the requested validation");
+  }
+}
+
+function hasRequestedEvidenceReuse(options) {
+  return [
+    options.expectedTargetSha,
+    options.expectedEvidencePolicy,
+    options.expectedEvidenceSha,
+    options.expectedChangedPaths,
+    options.expectedRootRunId,
+    options.expectedSelectedRunId,
+  ].some((value) => value !== undefined);
+}
+
 export function selectedChildKeys(parentJobs) {
   return new Set(
     CHILD_DISPATCHES.filter((child) => {
@@ -772,13 +903,23 @@ export function selectManifestParentJob(parentJobs, child, parentManifest, origi
   return currentJob;
 }
 
-function childRunIdsFromParentLog(log, repository = DEFAULT_REPO) {
+function childRunEvidenceFromParentLog(log, repository = DEFAULT_REPO) {
   const escapedRepo = repository.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-  const pattern = new RegExp(
+  const exactPattern = new RegExp(
+    `https://github\\.com/${escapedRepo}/actions/runs/([1-9][0-9]*) \\(attempt ([1-9][0-9]*)\\)`,
+    "gu",
+  );
+  const urlPattern = new RegExp(
     `https://github\\.com/${escapedRepo}/actions/runs/([1-9][0-9]*)`,
     "gu",
   );
-  return new Set(Array.from(log.matchAll(pattern), (match) => match[1]));
+  return {
+    exact: Array.from(log.matchAll(exactPattern), (match) => ({
+      runAttempt: Number(match[2]),
+      runId: match[1],
+    })),
+    runIds: [...new Set(Array.from(log.matchAll(urlPattern), (match) => match[1]))],
+  };
 }
 
 export function validateManifestChildRun(
@@ -812,9 +953,19 @@ export function validateManifestChildRun(
     throw new Error(`manifest child workflow mismatch: ${child.name}`);
   }
   selectManifestParentJob(parentJobs, child, parentManifest, originAttempt);
-  const emittedChildRunIds = childRunIdsFromParentLog(selectedParentJobLog, repository);
-  if (emittedChildRunIds.size !== 1 || !emittedChildRunIds.has(String(runId))) {
-    throw new Error(`manifest child run is not uniquely emitted by its parent job: ${child.name}`);
+  const emitted = childRunEvidenceFromParentLog(selectedParentJobLog, repository);
+  const exactBound =
+    emitted.exact.length === 1 &&
+    emitted.exact[0].runId === String(runId) &&
+    emitted.exact[0].runAttempt === Number(run.run_attempt);
+  const historicalUrlBound =
+    emitted.exact.length === 0 &&
+    emitted.runIds.length === 1 &&
+    emitted.runIds[0] === String(runId);
+  if (!exactBound && !historicalUrlBound) {
+    throw new Error(
+      `manifest child run and attempt are not uniquely emitted by its parent job: ${child.name}`,
+    );
   }
   if (
     child.manifestKey !== "npmTelegram" &&
@@ -1105,6 +1256,14 @@ export function createReleaseEvidenceClient(repository = DEFAULT_REPO) {
     getParentJobs(runId) {
       return findParentJobsAll(runId, normalizedRepository);
     },
+    getRef(fullRef) {
+      const refPath = String(fullRef)
+        .replace(/^refs\//u, "")
+        .split("/")
+        .map(encodeURIComponent)
+        .join("/");
+      return githubRestJson(`git/ref/${refPath}`, normalizedRepository);
+    },
     getRun(runId) {
       return githubRestJson(`actions/runs/${runId}`, normalizedRepository);
     },
@@ -1122,6 +1281,9 @@ export function createReleaseEvidenceClient(repository = DEFAULT_REPO) {
     loadManifest(runId, runAttempt, manifestPath) {
       return downloadParentManifestEvidence(runId, runAttempt, normalizedRepository, manifestPath);
     },
+    loadExecutionPlan(runId) {
+      return tryDownloadExecutionPlan(runId, normalizedRepository);
+    },
   };
 }
 
@@ -1198,6 +1360,20 @@ export function validateTrustedProducerIdentity(
   const shaPinned = SHA_PINNED_BRANCH_PATTERN.test(manifest.workflowRef ?? "");
   const protectedTagRoute = trustedIdentity.type === "tag";
   if (protectedTagRoute) {
+    let liveTag;
+    try {
+      liveTag = client.getRef(trustedIdentity.fullRef);
+    } catch (error) {
+      throw new Error(
+        `protected tooling tag is unavailable: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        { cause: error },
+      );
+    }
+    if (liveTag?.object?.sha !== trustedIdentity.sha) {
+      throw new Error("protected tooling tag moved after release validation was sealed");
+    }
     if (!shaPinned) {
       throw new Error("protected-tag release evidence must use a canonical release-ci branch");
     }
@@ -1335,8 +1511,28 @@ export function resolveVerifierIdentity(
   };
 }
 
-function validateStrictChildRun({ child, client, parentEvidence, parentJobs, repository, runId }) {
+function validateStrictChildRun({
+  child,
+  client,
+  parentEvidence,
+  parentJobs,
+  plannedChild,
+  releaseProfile,
+  repository,
+  runId,
+}) {
   const run = client.getRun(runId);
+  if (
+    plannedChild &&
+    (String(run.id) !== plannedChild.runId ||
+      Number(run.run_attempt) !== plannedChild.runAttempt ||
+      run.display_title !== plannedChild.displayTitle ||
+      run.head_branch !== plannedChild.workflowRef ||
+      run.head_sha !== plannedChild.workflowSha ||
+      workflowPath(run) !== `.github/workflows/${plannedChild.workflow}`)
+  ) {
+    throw new Error(`execution plan child dispatch tuple mismatch: ${child.name}`);
+  }
   const originAttempt = resolveManifestChildOriginAttempt(
     run,
     child,
@@ -1361,16 +1557,28 @@ function validateStrictChildRun({ child, client, parentEvidence, parentJobs, rep
     client.getJobLog(parentJob.id),
     repository,
   );
+  const jobs =
+    run.conclusion === "success" && child.manifestKey !== "productPerformance"
+      ? []
+      : client.getParentJobs(runId);
   if (
     run.repository?.full_name !== repository ||
-    run.status !== "completed" ||
-    run.conclusion !== "success" ||
-    run.head_sha !== parentEvidence.manifest.workflowSha
+    run.head_sha !== parentEvidence.manifest.workflowSha ||
+    !terminalPolicyPass(
+      {
+        conclusion: run.conclusion,
+        jobs,
+        key: child.manifestKey,
+        status: run.status,
+      },
+      releaseProfile,
+      parentEvidence.manifest.workflowRef,
+    )
   ) {
-    throw new Error(`manifest child run is not exact completed/success evidence: ${child.name}`);
+    throw new Error(`manifest child run does not pass release policy: ${child.name}`);
   }
   if (child.manifestKey === "productPerformance") {
-    validatePerformanceArtifactOnlyJobs(client.getParentJobs(runId), run.run_attempt);
+    validatePerformanceArtifactOnlyJobs(jobs, run.run_attempt);
   }
 
   return {
@@ -1381,6 +1589,7 @@ function validateStrictChildRun({ child, client, parentEvidence, parentJobs, rep
     headBranch: run.head_branch,
     parentJobId: String(parentJob.id),
     path: workflowPath(run),
+    policyPassed: true,
     role: child.manifestKey,
     runAttempt: normalizePositiveInteger(run.run_attempt, `${child.name} run attempt`),
     runId: String(run.id),
@@ -1398,6 +1607,12 @@ function validateStrictChildRun({ child, client, parentEvidence, parentJobs, rep
  *   manifestPath?: string,
  *   repository?: string,
  *   runId: string,
+ *   expectedChangedPaths?: string[],
+ *   expectedEvidencePolicy?: string,
+ *   expectedEvidenceSha?: string,
+ *   expectedRootRunId?: string,
+ *   expectedSelectedRunId?: string,
+ *   expectedTargetSha?: string,
  *   trustedWorkflowFullRef?: string,
  *   trustedWorkflowRef?: string,
  *   trustedWorkflowSha?: string,
@@ -1410,6 +1625,12 @@ export function validateReleaseRunEvidence(
     manifestPath,
     repository = DEFAULT_REPO,
     runId,
+    expectedChangedPaths,
+    expectedEvidencePolicy,
+    expectedEvidenceSha,
+    expectedRootRunId,
+    expectedSelectedRunId,
+    expectedTargetSha,
     trustedWorkflowFullRef,
     trustedWorkflowRef = "main",
     trustedWorkflowSha,
@@ -1437,6 +1658,14 @@ export function validateReleaseRunEvidence(
     repository: normalizedRepository,
     runId: normalizedRunId,
   });
+  const requestedReuse = {
+    expectedChangedPaths,
+    expectedEvidencePolicy,
+    expectedEvidenceSha,
+    expectedRootRunId,
+    expectedSelectedRunId,
+    expectedTargetSha,
+  };
   const producerIdentities = new Map([
     [
       currentEvidence.manifest.runId,
@@ -1475,6 +1704,15 @@ export function validateReleaseRunEvidence(
       (base, head) => evidenceClient.compareCommits(base, head),
     );
   }
+  if (hasRequestedEvidenceReuse(requestedReuse)) {
+    validateRequestedEvidenceReuse(
+      currentEvidence.manifest,
+      selectedEvidence.manifest,
+      rootEvidence.manifest,
+      requestedReuse,
+      (base, head) => evidenceClient.compareCommits(base, head),
+    );
+  }
 
   for (const evidence of [currentEvidence, selectedEvidence, rootEvidence]) {
     if (!producerIdentities.has(evidence.manifest.runId)) {
@@ -1492,23 +1730,64 @@ export function validateReleaseRunEvidence(
     }
   }
   const selectedKeys = requiredChildKeysForManifest(rootEvidence.manifest);
-  const expectedChildren = expectedSelectedChildDispatches(
-    rootEvidence.manifest.runId,
-    rootEvidence.manifest.runAttempt,
-    rootEvidence.manifest.workflowRef,
-    selectedKeys,
+  const executionPlanPayload = evidenceClient.loadExecutionPlan?.(rootEvidence.manifest.runId);
+  const executionPlan = executionPlanPayload
+    ? validateReleaseExecutionPlanArtifact(executionPlanPayload, {
+        parentRunId: rootEvidence.manifest.runId,
+        releaseProfile: rootEvidence.manifest.releaseProfile,
+        rerunGroup: rootEvidence.manifest.rerunGroup,
+        targetSha: rootEvidence.manifest.targetSha,
+        workflowRef: rootEvidence.manifest.workflowRef,
+        workflowSha: rootEvidence.manifest.workflowSha,
+      })
+    : undefined;
+  const plannedByKey = new Map(
+    (executionPlan?.children ?? []).map((plannedChild) => [plannedChild.key, plannedChild]),
   );
+  const expectedChildren = executionPlan
+    ? CHILD_DISPATCHES.filter((child) => selectedKeys.has(child.manifestKey)).map((child) => {
+        const plannedChild = plannedByKey.get(child.manifestKey);
+        if (
+          !plannedChild?.selected ||
+          !plannedChild.required ||
+          !plannedChild.runId ||
+          !plannedChild.runAttempt
+        ) {
+          throw new Error(`execution plan omits required child: ${child.name}`);
+        }
+        return Object.assign({}, child, {
+          displayTitle: plannedChild.displayTitle,
+          headBranch: plannedChild.workflowRef,
+          plannedChild,
+        });
+      })
+    : expectedSelectedChildDispatches(
+        rootEvidence.manifest.runId,
+        rootEvidence.manifest.runAttempt,
+        rootEvidence.manifest.workflowRef,
+        selectedKeys,
+      );
   const parentJobs = evidenceClient.getParentJobs(rootEvidence.manifest.runId);
-  const children = manifestChildEntries(rootEvidence.manifest, expectedChildren, selectedKeys).map(
-    ({ child, runId: childRunId }) =>
-      validateStrictChildRun({
-        child,
-        client: evidenceClient,
-        parentEvidence: rootEvidence,
-        parentJobs,
-        repository: normalizedRepository,
-        runId: childRunId,
-      }),
+  const childEntries = executionPlan
+    ? expectedChildren.map((child) => {
+        const manifestRunId = rootEvidence.manifest.childRunIds[child.manifestKey];
+        if (manifestRunId !== child.plannedChild.runId) {
+          throw new Error(`execution plan and manifest child identity differ: ${child.name}`);
+        }
+        return { child, runId: child.plannedChild.runId };
+      })
+    : manifestChildEntries(rootEvidence.manifest, expectedChildren, selectedKeys);
+  const children = childEntries.map(({ child, runId: childRunId }) =>
+    validateStrictChildRun({
+      child,
+      client: evidenceClient,
+      parentEvidence: rootEvidence,
+      parentJobs,
+      plannedChild: child.plannedChild,
+      releaseProfile: rootEvidence.manifest.releaseProfile,
+      repository: normalizedRepository,
+      runId: childRunId,
+    }),
   );
 
   const current = normalizedParentTuple(
@@ -1525,7 +1804,7 @@ export function validateReleaseRunEvidence(
   return canonicalJson({
     children,
     conclusions: {
-      allRequiredSucceeded: children.every((child) => child.conclusion === "success"),
+      allRequiredSucceeded: children.every((child) => child.policyPassed),
       children: childConclusions,
       current: current.conclusion,
       root: root.conclusion,
@@ -1542,6 +1821,12 @@ export function validateReleaseRunEvidence(
           selectedRunId: reuse.selectedRunId,
         }
       : null,
+    executionPlan: executionPlan
+      ? {
+          parentRunAttempt: executionPlan.parentRunAttempt,
+          sha256: executionPlan.sha256,
+        }
+      : null,
     manifest: rootEvidence.manifestJson,
     releaseProfile: rootEvidence.manifest.releaseProfile,
     repository: normalizedRepository,
@@ -1561,6 +1846,12 @@ export function validateReleaseRunEvidence(
 function parseReleaseCiSummaryArgs(argv) {
   const options = {
     intervalMs: 30_000,
+    expectedChangedPaths: undefined,
+    expectedEvidencePolicy: undefined,
+    expectedEvidenceSha: undefined,
+    expectedRootRunId: undefined,
+    expectedSelectedRunId: undefined,
+    expectedTargetSha: undefined,
     json: false,
     manifestPath: undefined,
     repository: DEFAULT_REPO,
@@ -1592,6 +1883,29 @@ function parseReleaseCiSummaryArgs(argv) {
       options.verifierSourceSha = argv[++index];
     } else if (argument === "--verifier-source-file") {
       options.verifierSourceFile = argv[++index];
+    } else if (argument === "--expected-target-sha") {
+      options.expectedTargetSha = argv[++index];
+    } else if (argument === "--expected-evidence-policy") {
+      options.expectedEvidencePolicy = argv[++index];
+    } else if (argument === "--expected-evidence-sha") {
+      options.expectedEvidenceSha = argv[++index];
+    } else if (argument === "--expected-root-run-id") {
+      options.expectedRootRunId = argv[++index];
+    } else if (argument === "--expected-selected-run-id") {
+      options.expectedSelectedRunId = argv[++index];
+    } else if (argument === "--expected-changed-paths-json") {
+      const value = argv[++index];
+      try {
+        options.expectedChangedPaths = JSON.parse(value);
+      } catch {
+        throw new Error("--expected-changed-paths-json requires a JSON array");
+      }
+      if (
+        !Array.isArray(options.expectedChangedPaths) ||
+        options.expectedChangedPaths.some((entry) => typeof entry !== "string")
+      ) {
+        throw new Error("--expected-changed-paths-json requires a JSON array");
+      }
     } else if (argument === "--json") {
       options.json = true;
     } else if (argument === "--watch") {
@@ -1628,7 +1942,7 @@ function printUsage() {
     [
       "usage: release-ci-summary.mjs <full-release-run-id>",
       "       release-ci-summary.mjs <full-release-run-id> --watch [--interval seconds]",
-      "       release-ci-summary.mjs --validate-run <id> [--repo owner/name] [--trusted-workflow-ref main --trusted-workflow-full-ref refs/heads/main] [--trusted-workflow-sha sha] [--manifest path] [--verifier-source-sha sha --verifier-source-file path] --json",
+      "       release-ci-summary.mjs --validate-run <id> [--repo owner/name] [--trusted-workflow-ref main --trusted-workflow-full-ref refs/heads/main] [--trusted-workflow-sha sha] [--manifest path] [--verifier-source-sha sha --verifier-source-file path] [--expected-target-sha sha --expected-evidence-sha sha --expected-evidence-policy policy --expected-root-run-id id --expected-selected-run-id id --expected-changed-paths-json json] --json",
     ].join("\n"),
   );
 }
@@ -1658,6 +1972,81 @@ function terminalParentJobFailures(parent) {
     .map((job) => String(job.name || "unnamed parent job"));
 }
 
+export function tryReadReleaseDecisionArtifact(
+  parent,
+  runId,
+  repository,
+  runReleaseCiGhImpl = runReleaseCiGh,
+) {
+  const artifactName = `full-release-decision-${runId}-${parent.attempt}`;
+  const downloadDir = mkdtempSync(join(tmpdir(), "openclaw-release-decision-watch-"));
+  try {
+    try {
+      runReleaseCiGhImpl(
+        [
+          "run",
+          "download",
+          String(runId),
+          "--repo",
+          repository,
+          "--name",
+          artifactName,
+          "--dir",
+          downloadDir,
+        ],
+        { stdio: ["ignore", "ignore", "pipe"] },
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (
+        /no valid artifacts found|artifact .* not found|could not find any artifacts/iu.test(
+          message,
+        )
+      ) {
+        return undefined;
+      }
+      if (classifyReleaseGhTransportError(error) === "transient") {
+        console.warn(`release decision artifact unavailable this poll; retrying: ${message}`);
+        return undefined;
+      }
+      throw new Error(`release decision artifact read failed: ${message}`, { cause: error });
+    }
+    const path = join(downloadDir, "full-release-decision.json");
+    if (!statSync(path, { throwIfNoEntry: false })) {
+      throw new Error(`release decision artifact ${artifactName} omitted its manifest`);
+    }
+    if (statSync(path).size > MAX_RELEASE_STATE_BYTES) {
+      throw new Error(`release decision artifact ${artifactName} exceeds the size limit`);
+    }
+    return validateReleaseStateArtifact(
+      JSON.parse(readFileSync(path, "utf8")),
+      {
+        parentRunAttempt: parent.attempt,
+        parentRunId: String(runId),
+        workflowSha: parent.headSha,
+      },
+      "decision",
+    );
+  } finally {
+    rmSync(downloadDir, { force: true, recursive: true });
+  }
+}
+
+function releaseDecisionBlockedDuringDrain(parent, runId, repository) {
+  const jobs = parent.jobs ?? [];
+  const decision = jobs.find((job) => job.name === "Release Decision");
+  const drain = jobs.find((job) => job.name === "Diagnostic Drain");
+  if (
+    decision?.status !== "completed" ||
+    SUCCESSFUL_PARENT_JOB_CONCLUSIONS.has(String(decision.conclusion ?? "")) ||
+    !drain ||
+    drain.status === "completed"
+  ) {
+    return undefined;
+  }
+  return tryReadReleaseDecisionArtifact(parent, runId, repository);
+}
+
 function summarizeReleaseCiRun(options) {
   execFileSync(
     process.execPath,
@@ -1683,13 +2072,23 @@ async function watchReleaseCiRun(options) {
       "--repo",
       options.repository,
       "--json",
-      "status,conclusion,attempt,jobs",
+      "status,conclusion,attempt,headSha,jobs",
     ]);
     const fingerprint = releaseCiWatchFingerprint(parent);
     if (fingerprint !== previousFingerprint) {
       summarizeReleaseCiRun(options);
       previousFingerprint = fingerprint;
     }
+    const blockedDuringDrain = releaseDecisionBlockedDuringDrain(
+      parent,
+      options.runId,
+      options.repository,
+    );
+    if (blockedDuringDrain) {
+      throw new Error(
+        `full release run ${options.runId} stopped at Release Decision:\n${formatReleaseStateOutcome(blockedDuringDrain)}`,
+      );
+    }
     const failedJobs = terminalParentJobFailures(parent);
     if (failedJobs.length > 0) {
       throw new Error(
@@ -1724,6 +2123,12 @@ async function main() {
   if (options.validate) {
     try {
       const evidence = validateReleaseRunEvidence({
+        expectedChangedPaths: options.expectedChangedPaths,
+        expectedEvidencePolicy: options.expectedEvidencePolicy,
+        expectedEvidenceSha: options.expectedEvidenceSha,
+        expectedRootRunId: options.expectedRootRunId,
+        expectedSelectedRunId: options.expectedSelectedRunId,
+        expectedTargetSha: options.expectedTargetSha,
         manifestPath: options.manifestPath,
         repository,
         runId,
diff --git a/test/scripts/ci-workflow-guards.test.ts b/test/scripts/ci-workflow-guards.test.ts
index 74d932f74383..4779ab44759c 100644
--- a/test/scripts/ci-workflow-guards.test.ts
+++ b/test/scripts/ci-workflow-guards.test.ts
@@ -7255,7 +7255,7 @@ printf '%s\n' "\${CURL_SUCCESS_IP:-203.0.113.7}"
     );
     expect(localeStep.run).toBe("pnpm ui:i18n:check");
     expect(readFileSync(".github/workflows/full-release-validation.yml", "utf8")).toContain(
-      'dispatch_and_wait ci.yml "$dispatch_run_name"',
+      'dispatch_child ci.yml "$dispatch_run_name"',
     );
   });
 
@@ -7689,7 +7689,7 @@ printf '%s\n' "\${CURL_SUCCESS_IP:-203.0.113.7}"
     const compatibilityJob = workflow.jobs["checks-node-compat"];
     const fullReleaseWorkflow = readWorkflow(".github/workflows/full-release-validation.yml");
     const fullReleaseDispatch = fullReleaseWorkflow.jobs.normal_ci.steps.find(
-      (step: WorkflowStep) => step.name === "Dispatch and monitor CI",
+      (step: WorkflowStep) => step.name === "Dispatch CI",
     );
 
     expect(compatibilityJob.name).toBe("checks-node-compat-node22");
@@ -7697,7 +7697,7 @@ printf '%s\n' "\${CURL_SUCCESS_IP:-203.0.113.7}"
       "needs.preflight.outputs.run_build_artifacts == 'true' && github.event_name == 'workflow_dispatch'",
     );
     expect(fullReleaseDispatch.env.CHILD_WORKFLOW_KIND).toBe("ci");
-    expect(fullReleaseDispatch.run).toContain('dispatch_and_wait ci.yml "$dispatch_run_name"');
+    expect(fullReleaseDispatch.run).toContain('dispatch_child ci.yml "$dispatch_run_name"');
     expect(fullReleaseDispatch.run).toContain('-f target_ref="$TARGET_SHA"');
   });
 
@@ -9023,7 +9023,7 @@ printf '%s\n' "\${CURL_SUCCESS_IP:-203.0.113.7}"
     const telegramWorkflow = readWorkflow(".github/workflows/openclaw-release-telegram-qa.yml");
     const telegramProvenanceHelper = readFileSync("scripts/release-telegram-provenance.sh", "utf8");
     const fullReleaseDispatchStep = fullReleaseWorkflow.jobs.release_checks.steps.find(
-      (step: WorkflowStep) => step.name === "Dispatch and monitor release checks",
+      (step: WorkflowStep) => step.name === "Dispatch release checks",
     );
     const dispatchStep = releaseWorkflow.jobs.qa_live_telegram_release_checks.steps.find(
       (step: WorkflowStep) => step.name === "Dispatch and await trusted Telegram QA",
diff --git a/test/scripts/full-release-validation-at-sha.test.ts b/test/scripts/full-release-validation-at-sha.test.ts
index 5e2348f48ca8..1f3e84ba6d95 100644
--- a/test/scripts/full-release-validation-at-sha.test.ts
+++ b/test/scripts/full-release-validation-at-sha.test.ts
@@ -2,7 +2,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { parse as parseYaml } from "yaml";
 import {
   assertTrustedWorkflowHarness,
@@ -10,10 +10,13 @@ import {
   FULL_RELEASE_WAIT_TIMEOUT_MINUTES,
   parseArgs,
   releaseProfileForTarget,
+  releaseDecisionStopsForeground,
   releaseEvidenceVerificationArgs,
   releaseEvidenceVerifierPath,
   resolveRemoteTargetRefSha,
   shouldDeleteTemporaryWorkflowRef,
+  tryReadReleaseDecision,
+  validateReleaseDecisionPayload,
   verifyTargetRef,
   verifyTrustedWorkflowRef,
 } from "../../scripts/full-release-validation-at-sha.mts";
@@ -160,7 +163,10 @@ if (args[0] === "workflow" && args[1] === "run") {
   }
   console.log("https://github.com/openclaw/openclaw/actions/runs/123");
 } else if (args[0] === "api" && args.at(-1).endsWith("/actions/runs/123")) {
-  console.log(JSON.stringify({ status: "completed", conclusion: "success", head_sha: process.env.MOCK_WORKFLOW_SHA }));
+  console.log(JSON.stringify({ status: "completed", conclusion: "success", head_sha: process.env.MOCK_WORKFLOW_SHA, run_attempt: 1 }));
+} else if (args[0] === "run" && args[1] === "download") {
+  console.error("no valid artifacts found");
+  process.exit(1);
 } else {
   console.error("unexpected gh call: " + args.join(" "));
   process.exit(2);
@@ -560,12 +566,84 @@ describe("full-release-validation-at-sha", () => {
     expect(source).toContain("const remainingMs = deadline - Date.now();");
     expect(source).toContain("Math.min(FULL_RELEASE_WAIT_POLL_INTERVAL_MS, remainingMs)");
     expect(source).toContain("Parent run progress after ${elapsedMinutes}m");
+    expect(source).toContain("formatReleaseStateOutcome(releaseDecision)");
     expect(source).toContain(
       "Timed out after ${FULL_RELEASE_WAIT_TIMEOUT_MINUTES} minutes waiting for Full Release Validation",
     );
     expect(source).not.toContain("attempt < 480");
   });
 
+  it("binds early release decisions to the exact parent attempt and tooling SHA", () => {
+    const payload = {
+      kind: "openclaw.full-release-decision",
+      mode: "decision",
+      parentRunAttempt: 2,
+      sourceParentRunAttempt: 1,
+      parentRunId: "123",
+      activeRunIds: ["101"],
+      blockers: [{ child: "normalCi", job: "test", runId: "101" }],
+      cancellation: { cancelledRunIds: [], requested: false },
+      children: {},
+      errors: [],
+      executionPlanSha256: "c".repeat(64),
+      releaseProfile: "stable",
+      rerunGroup: "ci",
+      state: "blocked_diagnostics_running",
+      targetSha: "b".repeat(40),
+      version: 2,
+      workflowRef: "main",
+      workflowSha: "a".repeat(40),
+    };
+    expect(
+      validateReleaseDecisionPayload(payload, {
+        parentRunAttempt: 2,
+        parentRunId: "123",
+        workflowSha: "a".repeat(40),
+      }),
+    ).toMatchObject(payload);
+    expect(releaseDecisionStopsForeground("blocked_diagnostics_running")).toBe(true);
+    expect(releaseDecisionStopsForeground("passed")).toBe(false);
+    expect(() =>
+      validateReleaseDecisionPayload(
+        { ...payload, parentRunAttempt: 3 },
+        {
+          parentRunAttempt: 2,
+          parentRunId: "123",
+          workflowSha: "a".repeat(40),
+        },
+      ),
+    ).toThrow("binding is invalid");
+  });
+
+  it("treats only transient Release Decision download failures as unavailable this poll", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      expect(
+        tryReadReleaseDecision("123", 1, "a".repeat(40), () => ({
+          error: undefined,
+          signal: null,
+          status: 1,
+          stderr: "HTTP 503: Server Error",
+          stdout: "",
+        })),
+      ).toBeUndefined();
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining("Release Decision artifact unavailable this poll"),
+      );
+      expect(() =>
+        tryReadReleaseDecision("123", 1, "a".repeat(40), () => ({
+          error: undefined,
+          signal: null,
+          status: 1,
+          stderr: "HTTP 403: Bad credentials",
+          stdout: "",
+        })),
+      ).toThrow("Release Decision artifact download failed");
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
   it("bounds GitHub reads without applying a timeout to workflow dispatch", () => {
     const source = readFileSync("scripts/full-release-validation-at-sha.mts", "utf8");
     expect(source).toContain("timeout: GH_READ_TIMEOUT_MS");
diff --git a/test/scripts/full-release-validation-state.test.ts b/test/scripts/full-release-validation-state.test.ts
new file mode 100644
index 000000000000..765c911193c2
--- /dev/null
+++ b/test/scripts/full-release-validation-state.test.ts
@@ -0,0 +1,1312 @@
+import { spawn, spawnSync } from "node:child_process";
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { releaseExecutionPlanSha256 } from "../../scripts/full-release-validation-policy.mjs";
+import {
+  affectedActiveRunIds,
+  buildReleaseExecutionPlan,
+  buildReleaseExecutionPlanArtifact,
+  buildReleaseStateArtifact,
+  classifyReleaseGhTransportError,
+  classifyReleaseSnapshot,
+  formatReleaseStateOutcome,
+  selectReleaseStateArtifacts,
+  validateChildBinding,
+  validateReleaseExecutionPlanArtifact,
+  verifyReleaseStateArtifacts,
+} from "../../scripts/full-release-validation-state.mjs";
+import { waitForChildClose, waitForFile } from "../helpers/process-wait.js";
+
+const SCRIPT = resolve("scripts/full-release-validation-state.mjs");
+const SHA = "a".repeat(40);
+const TARGET_SHA = "b".repeat(40);
+const TRUSTED_MAIN = { fullRef: "refs/heads/main", ref: "main", sha: SHA };
+
+function evidenceManifest() {
+  return { runAttempt: 1, runId: "99", targetSha: TARGET_SHA };
+}
+
+function generatedManifest(planArtifact: Record<string, any>): Record<string, any> {
+  return {
+    childRuns: {
+      normalCi: "101",
+      npmTelegram: "",
+      pluginPrerelease: "",
+      productPerformance: { blocking: true, conclusion: "", runId: "" },
+      releaseChecks: "",
+    },
+    controls: {
+      performanceBlocking: true,
+      performanceReportPublication: "artifact-only",
+      stableSoakRequired: false,
+    },
+    executionPlanSha256: planArtifact.sha256,
+    releaseProfile: "stable",
+    rerunGroup: "ci",
+    runAttempt: 2,
+    runId: "77",
+    runReleaseSoak: "false",
+    sourceParentRunAttempt: 1,
+    targetRef: "main",
+    targetSha: TARGET_SHA,
+    version: 3,
+    workflowFullRef: "refs/heads/release-ci/tooling",
+    workflowName: "Full Release Validation",
+    workflowRef: "release-ci/tooling",
+    workflowRefType: "branch",
+    workflowSha: SHA,
+  };
+}
+
+function child(key: string, overrides: Record<string, unknown> = {}) {
+  return {
+    conclusion: "",
+    dispatchName: `Dispatch ${key}`,
+    displayTitle: key,
+    errors: [],
+    jobs: [],
+    key,
+    required: true,
+    result: "success",
+    runAttempt: 1,
+    runId: "101",
+    selected: true,
+    source: "fresh",
+    status: "in_progress",
+    url: "https://example.invalid/runs/101",
+    workflow: "ci.yml",
+    workflowRef: "release-ci/tooling",
+    workflowSha: SHA,
+    ...overrides,
+  };
+}
+
+function plan(overrides: Record<string, unknown> = {}) {
+  return buildReleaseExecutionPlan({
+    children: {
+      normalCi: { result: "success", runAttempt: 1, runId: "101" },
+      npmTelegram: { result: "success", runAttempt: 1, runId: "404" },
+      pluginPrerelease: { result: "success", runAttempt: 1, runId: "202" },
+      productPerformance: { result: "success", runAttempt: 1, runId: "505" },
+      releaseChecks: { result: "success", runAttempt: 1, runId: "303" },
+    },
+    dockerPreflightResult: "success",
+    evidenceReuse: false,
+    parentRunAttempt: 2,
+    parentRunId: "77",
+    prepareCandidateResult: "success",
+    rerunGroup: "all",
+    resolveTargetResult: "success",
+    workflowRef: "release-ci/tooling",
+    workflowSha: SHA,
+    ...overrides,
+  });
+}
+
+function executionPlan(
+  overrides: Record<string, unknown> = {},
+  artifactOverrides: Record<string, unknown> = {},
+) {
+  const expected = {
+    parentRunAttempt: 1,
+    parentRunId: "77",
+    targetSha: TARGET_SHA,
+    workflowRef: "release-ci/tooling",
+    workflowSha: SHA,
+    ...((artifactOverrides.expected as Record<string, unknown> | undefined) ?? {}),
+  };
+  const built = plan({ ...overrides, parentRunAttempt: expected.parentRunAttempt });
+  return buildReleaseExecutionPlanArtifact({
+    children: built.children,
+    expected,
+    gates: built.gates,
+    releaseProfile: "stable",
+    rerunGroup: String(overrides.rerunGroup ?? "all"),
+    trustedWorkflow: TRUSTED_MAIN,
+    ...artifactOverrides,
+  });
+}
+
+function reusedEvidenceChildren() {
+  return [
+    ["normalCi", "101", "CI"],
+    ["pluginPrerelease", "202", "Plugin Prerelease"],
+    ["releaseChecks", "303", "OpenClaw Release Checks"],
+    ["productPerformance", "505", "OpenClaw Performance"],
+  ].map(([role, runId, name]) => ({
+    displayTitle: `${name} full-release-validation-99-1`,
+    headBranch: "release-ci/tooling",
+    role,
+    runAttempt: 1,
+    runId,
+    url: `https://example.invalid/runs/${runId}`,
+    workflowSha: SHA,
+  }));
+}
+
+describe("full release execution plan", () => {
+  it.each([
+    ["HTTP 429: rate limited", "transient"],
+    ["HTTP 503: Server Error", "transient"],
+    ["spawnSync gh ETIMEDOUT", "transient"],
+    ["read ECONNRESET", "transient"],
+    ["getaddrinfo EAI_AGAIN api.github.com", "transient"],
+    ["unexpected EOF", "transient"],
+    ["HTTP 401: Bad credentials", "hard"],
+    ["HTTP 403: secondary rate limit", "hard"],
+    ["unknown flag: --name\nUsage: gh run download", "hard"],
+  ] as const)("classifies GitHub transport error %s as %s", (message, expected) => {
+    expect(
+      classifyReleaseGhTransportError(Object.assign(new Error(message), { stderr: message })),
+    ).toBe(expected);
+  });
+
+  it("keeps required coverage selected when dispatch output is missing", () => {
+    const result = plan({
+      children: { normalCi: { result: "success", runAttempt: "", runId: "" } },
+      rerunGroup: "ci",
+    });
+    expect(result.children.find((entry) => entry.key === "normalCi")).toMatchObject({
+      required: true,
+      runAttempt: null,
+      runId: "",
+      selected: true,
+    });
+    expect(
+      classifyReleaseSnapshot({
+        children: result.children.map((entry) => ({
+          ...entry,
+          errors: [],
+          jobs: [],
+          status: "missing",
+        })),
+        releaseProfile: "stable",
+        workflowRef: "release-ci/tooling",
+      }),
+    ).toMatchObject({
+      blockers: [expect.objectContaining({ kind: "dispatch_missing" })],
+      state: "blocked_complete",
+    });
+  });
+
+  it.each(["install-smoke", "qa-parity", "qa-live"])(
+    "does not require candidate preparation for focused %s",
+    (rerunGroup) => {
+      expect(
+        plan({ prepareCandidateResult: "skipped", rerunGroup }).gates.find(
+          (entry) => entry.name === "Prepare shared release candidate",
+        ),
+      ).toMatchObject({ required: false });
+    },
+  );
+
+  it("does not prepare a candidate for published packages", () => {
+    expect(
+      plan({
+        packageAcceptancePackageSpec: "openclaw@2026.8.4-beta.3",
+        prepareCandidateResult: "skipped",
+        rerunGroup: "package",
+      }).gates.at(-1),
+    ).toMatchObject({ required: false });
+  });
+
+  it("requires live-e2e candidate preparation only without a suite filter", () => {
+    expect(plan({ rerunGroup: "live-e2e" }).gates.at(-1)).toMatchObject({ required: true });
+    expect(plan({ liveSuiteFilter: "discord", rerunGroup: "live-e2e" }).gates.at(-1)).toMatchObject(
+      {
+        required: false,
+      },
+    );
+  });
+
+  it("rejects a digest-valid plan with an incomplete reuse selection tuple", () => {
+    const artifact = executionPlan(
+      { rerunGroup: "ci" },
+      {
+        evidenceReuse: {
+          changedPaths: [],
+          evidenceSha: TARGET_SHA,
+          policy: "exact-target-full-validation-v1",
+          requested: true,
+          rootRunId: "99",
+          runUrl: "https://example.invalid/runs/99",
+          selectedRunId: "99",
+          sourceManifest: evidenceManifest(),
+        },
+      },
+    );
+    const incompleteArtifact = {
+      ...artifact,
+      evidenceReuse: { ...artifact.evidenceReuse, selectedRunId: "" },
+    };
+    const digestValidArtifact = {
+      ...incompleteArtifact,
+      sha256: releaseExecutionPlanSha256(incompleteArtifact),
+    };
+    expect(() => validateReleaseExecutionPlanArtifact(digestValidArtifact)).toThrow(
+      "release execution plan evidence reuse binding is invalid",
+    );
+  });
+});
+
+describe("release decision policy", () => {
+  it("reports a decisive blocker while unrelated diagnostics continue", () => {
+    const result = classifyReleaseSnapshot({
+      children: [
+        child("normalCi", {
+          jobs: [{ conclusion: "failure", name: "test", status: "completed" }],
+        }),
+        child("releaseChecks", { runId: "202" }),
+      ],
+      releaseProfile: "stable",
+      workflowRef: "main",
+    });
+    expect(result).toMatchObject({
+      activeRunIds: ["101", "202"],
+      state: "blocked_diagnostics_running",
+    });
+  });
+
+  it("keeps advisory QA and beta performance failures non-blocking", () => {
+    const result = classifyReleaseSnapshot({
+      children: [
+        child("releaseChecks", {
+          conclusion: "failure",
+          jobs: [
+            {
+              conclusion: "failure",
+              name: "Run QA Lab runtime-pair lane (core)",
+              status: "completed",
+            },
+            { conclusion: "success", name: "Verify release checks", status: "completed" },
+          ],
+          status: "completed",
+        }),
+        child("productPerformance", {
+          conclusion: "failure",
+          jobs: [{ conclusion: "failure", name: "benchmark", status: "completed" }],
+          runId: "202",
+          status: "completed",
+        }),
+      ],
+      releaseProfile: "beta",
+      workflowRef: "main",
+    });
+    expect(result).toMatchObject({ blockers: [], errors: [], state: "passed" });
+  });
+
+  it("preserves a blocker and an API error independently", () => {
+    const result = classifyReleaseSnapshot({
+      children: [
+        child("normalCi", {
+          jobs: [{ conclusion: "failure", name: "test", status: "completed" }],
+        }),
+        child("releaseChecks", {
+          errors: [{ kind: "api_error", message: "HTTP 503", runId: "202" }],
+          runId: "202",
+          status: "unknown",
+        }),
+      ],
+      releaseProfile: "stable",
+      workflowRef: "main",
+    });
+    expect(result).toMatchObject({
+      blockers: [expect.objectContaining({ job: "test" })],
+      errors: [expect.objectContaining({ kind: "api_error" })],
+      state: "orchestration_error",
+    });
+  });
+
+  it("binds the exact child attempt and tooling tuple", () => {
+    const result = validateChildBinding(
+      child("normalCi"),
+      {
+        conclusion: "",
+        created_at: "2026-08-21T00:00:00Z",
+        display_title: "normalCi",
+        event: "workflow_dispatch",
+        head_branch: "release-ci/tooling",
+        head_sha: SHA,
+        html_url: "https://example.invalid/runs/101",
+        id: 101,
+        path: ".github/workflows/ci.yml@refs/heads/release-ci/tooling",
+        run_attempt: 2,
+        status: "in_progress",
+        updated_at: "2026-08-21T00:01:00Z",
+      },
+      [],
+    );
+    expect(result.errors).toEqual([
+      expect.objectContaining({
+        kind: "provenance_mismatch",
+        message: expect.stringContaining("attempt"),
+      }),
+    ]);
+  });
+
+  it("cancels only exact active affected children", () => {
+    expect(
+      affectedActiveRunIds(
+        [
+          child("normalCi"),
+          child("releaseChecks", { runId: "202" }),
+          child("npmTelegram", { runId: "303", status: "completed" }),
+        ],
+        [{ runId: "101" }, { runId: "303" }],
+      ),
+    ).toEqual(["101"]);
+  });
+});
+
+describe("release state artifacts", () => {
+  function artifact(
+    mode: "decision" | "drain",
+    parentRunAttempt = 2,
+    sealedPlan = executionPlan({ rerunGroup: "ci" }),
+  ) {
+    const plannedChild = sealedPlan.children.find(
+      (entry: Record<string, any>) => entry.key === "normalCi",
+    );
+    const children = [
+      child("normalCi", {
+        ...plannedChild,
+        conclusion: "success",
+        createdAt: "2026-08-21T00:00:00Z",
+        status: "completed",
+        updatedAt: "2026-08-21T00:01:00Z",
+      }),
+    ];
+    return buildReleaseStateArtifact({
+      children,
+      decision: { activeRunIds: [], blockers: [], errors: [], state: "passed" },
+      executionPlan: sealedPlan,
+      expected: {
+        parentRunAttempt,
+        parentRunId: "77",
+        targetSha: TARGET_SHA,
+        workflowRef: "release-ci/tooling",
+        workflowSha: SHA,
+      },
+      mode,
+      releaseProfile: "stable",
+      rerunGroup: "ci",
+    });
+  }
+
+  it("uses one policy for decision, drain, and final verification", () => {
+    expect(
+      verifyReleaseStateArtifacts(
+        executionPlan({ rerunGroup: "ci" }),
+        artifact("decision"),
+        artifact("drain"),
+        {
+          parentRunAttempt: 2,
+          parentRunId: "77",
+          releaseProfile: "stable",
+          rerunGroup: "ci",
+          targetSha: TARGET_SHA,
+          workflowSha: SHA,
+        },
+      ),
+    ).toMatchObject({ decision: { state: "passed" }, drain: { state: "passed" } });
+  });
+
+  it("selects the newest decision and drain independently across asymmetric retries", () => {
+    const sealedPlan = executionPlan({ rerunGroup: "ci" });
+    const selected = selectReleaseStateArtifacts(
+      sealedPlan,
+      [
+        { name: "full-release-decision-77-1", payload: artifact("decision", 1, sealedPlan) },
+        { name: "full-release-decision-77-2", payload: artifact("decision", 2, sealedPlan) },
+      ],
+      [{ name: "full-release-diagnostics-77-1", payload: artifact("drain", 1, sealedPlan) }],
+      {
+        maxParentRunAttempt: 3,
+        parentRunId: "77",
+        releaseProfile: "stable",
+        rerunGroup: "ci",
+        targetSha: TARGET_SHA,
+        workflowRef: "release-ci/tooling",
+        workflowSha: SHA,
+      },
+    );
+    expect(selected.sourceAttempts).toEqual({ decision: 2, drain: 1, executionPlan: 1 });
+  });
+
+  function selectFromFilesystem(layout: "asymmetric" | "multi" | "single") {
+    const root = mkdtempSync(join(tmpdir(), `frv-select-${layout}-`));
+    const executionPlanPath = join(root, "plan.json");
+    const decisionRoot = join(root, "decisions");
+    const drainRoot = join(root, "drains");
+    const decisionPath = join(root, "selected-decision.json");
+    const drainPath = join(root, "selected-drain.json");
+    const outputPath = join(root, "output.txt");
+    const sealedPlan = executionPlan({ rerunGroup: "ci" });
+    mkdirSync(decisionRoot);
+    mkdirSync(drainRoot);
+    writeFileSync(executionPlanPath, JSON.stringify(sealedPlan));
+    const writeCandidate = (
+      candidateRoot: string,
+      prefix: string,
+      filename: string,
+      mode: "decision" | "drain",
+      attempt: number,
+      direct: boolean,
+    ) => {
+      const target = direct
+        ? join(candidateRoot, filename)
+        : join(candidateRoot, `${prefix}-77-${attempt}`, filename);
+      mkdirSync(resolve(target, ".."), { recursive: true });
+      writeFileSync(target, JSON.stringify(artifact(mode, attempt, sealedPlan)));
+    };
+    if (layout === "single") {
+      writeCandidate(
+        decisionRoot,
+        "full-release-decision",
+        "full-release-decision.json",
+        "decision",
+        2,
+        true,
+      );
+      writeCandidate(
+        drainRoot,
+        "full-release-diagnostics",
+        "full-release-diagnostic-manifest.json",
+        "drain",
+        2,
+        true,
+      );
+    } else {
+      writeCandidate(
+        decisionRoot,
+        "full-release-decision",
+        "full-release-decision.json",
+        "decision",
+        1,
+        false,
+      );
+      writeCandidate(
+        decisionRoot,
+        "full-release-decision",
+        "full-release-decision.json",
+        "decision",
+        2,
+        false,
+      );
+      writeCandidate(
+        drainRoot,
+        "full-release-diagnostics",
+        "full-release-diagnostic-manifest.json",
+        "drain",
+        layout === "asymmetric" ? 1 : 2,
+        false,
+      );
+    }
+    const result = spawnSync(process.execPath, [SCRIPT, "select"], {
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        DIAGNOSTIC_DRAIN_ATTEMPTS_PATH: drainRoot,
+        DIAGNOSTIC_DRAIN_PATH: drainPath,
+        GITHUB_OUTPUT: outputPath,
+        GITHUB_REF_NAME: "release-ci/tooling",
+        GITHUB_RUN_ATTEMPT: "3",
+        GITHUB_RUN_ID: "77",
+        GITHUB_SHA: SHA,
+        RELEASE_DECISION_ATTEMPTS_PATH: decisionRoot,
+        RELEASE_DECISION_PATH: decisionPath,
+        RELEASE_EXECUTION_PLAN_PATH: executionPlanPath,
+        RELEASE_PROFILE: "stable",
+        RERUN_GROUP: "ci",
+        TARGET_SHA,
+      },
+      timeout: 10_000,
+    });
+    expect(result.status, result.stderr).toBe(0);
+    return readFileSync(outputPath, "utf8");
+  }
+
+  it("selects state from the direct-file layout used for one artifact match", () => {
+    expect(selectFromFilesystem("single")).toContain("decision_source_attempt=2");
+  });
+
+  it("selects the newest state from the subdirectory layout used for multiple matches", () => {
+    expect(selectFromFilesystem("multi")).toContain("drain_source_attempt=2");
+  });
+
+  it("selects asymmetric Decision and Drain retries from filesystem artifacts", () => {
+    expect(selectFromFilesystem("asymmetric")).toContain("drain_source_attempt=1");
+  });
+
+  it.each([
+    {
+      mutate: (drain: Record<string, any>) => {
+        drain.children.normalCi.displayTitle = "nearby title";
+      },
+      name: "changed child display title",
+      reason: "provenance differs",
+    },
+    {
+      mutate: (drain: Record<string, any>) => {
+        drain.children.normalCi.workflow = "nearby.yml";
+      },
+      name: "changed child workflow",
+      reason: "provenance differs",
+    },
+    {
+      mutate: (drain: Record<string, any>) => {
+        drain.children.normalCi.workflowRef = "main";
+      },
+      name: "changed child workflow ref",
+      reason: "provenance differs",
+    },
+    {
+      mutate: (drain: Record<string, any>) => {
+        drain.children.normalCi.workflowSha = "f".repeat(40);
+      },
+      name: "changed child tooling SHA",
+      reason: "provenance differs",
+    },
+    {
+      mutate: (drain: Record<string, any>) => {
+        drain.children.normalCi.conclusion = "failure";
+      },
+      name: "failed child hidden behind passed state",
+      reason: "canonical terminal release policy",
+    },
+    {
+      mutate: (drain: Record<string, any>) => {
+        drain.children.normalCi.errors = [{ kind: "api_error", message: "hidden" }];
+      },
+      name: "hidden child collector error",
+      reason: "contains collector errors",
+    },
+  ])("rejects a malformed passed drain with $name", ({ mutate, reason }) => {
+    const sealedPlan = executionPlan({ rerunGroup: "ci" });
+    const decision = artifact("decision", 2, sealedPlan);
+    const drain = structuredClone(artifact("drain", 2, sealedPlan));
+    mutate(drain);
+    expect(() =>
+      verifyReleaseStateArtifacts(sealedPlan, decision, drain, {
+        maxParentRunAttempt: 2,
+        parentRunId: "77",
+        releaseProfile: "stable",
+        rerunGroup: "ci",
+        targetSha: TARGET_SHA,
+        workflowRef: "release-ci/tooling",
+        workflowSha: SHA,
+      }),
+    ).toThrow(reason);
+  });
+
+  it("uses state-specific operator guidance", () => {
+    expect(
+      formatReleaseStateOutcome({
+        blockers: [{ conclusion: "failure", job: "test", url: "https://example.invalid/job" }],
+        errors: [],
+        state: "blocked_diagnostics_running",
+      }),
+    ).toContain("diagnose now, retry later");
+    expect(
+      formatReleaseStateOutcome({ blockers: [], errors: [], state: "blocked_complete" }),
+    ).not.toContain("still collecting");
+  });
+});
+
+describe("collector subprocess", () => {
+  it.each([
+    {
+      changedPaths: [],
+      evidenceSha: TARGET_SHA,
+      name: "exact-target",
+      policy: "exact-target-full-validation-v1",
+      trustedWorkflow: TRUSTED_MAIN,
+    },
+    {
+      changedPaths: ["CHANGELOG.md"],
+      evidenceSha: "c".repeat(40),
+      name: "changelog-only",
+      policy: "changelog-only-release-v1",
+      trustedWorkflow: {
+        fullRef: `refs/tags/release-publish/${SHA.slice(0, 12)}-123`,
+        ref: `release-publish/${SHA.slice(0, 12)}-123`,
+        sha: SHA,
+      },
+    },
+  ])("seals and revalidates the complete $name reuse tuple", (reuse) => {
+    const root = mkdtempSync(join(tmpdir(), "frv-plan-reuse-"));
+    const output = join(root, "full-release-execution-plan.json");
+    const validator = join(root, "release-evidence-validator.mjs");
+    const validatorArgs = join(root, "validator-args.json");
+    writeFileSync(
+      validator,
+      `import { writeFileSync } from "node:fs";
+const args = process.argv.slice(2);
+writeFileSync(process.env.FRV_VALIDATOR_ARGS, JSON.stringify(args));
+const value = (flag) => args[args.indexOf(flag) + 1];
+const expected = JSON.parse(process.env.FRV_EXPECTED_REUSE);
+for (const [flag, wanted] of Object.entries(expected)) {
+  if (value(flag) !== wanted) {
+    console.error(\`\${flag} mismatch: \${value(flag)} != \${wanted}\`);
+    process.exit(1);
+  }
+}
+console.log(JSON.stringify({
+  children: JSON.parse(process.env.FRV_REUSED_CHILDREN),
+  manifest: JSON.parse(process.env.FRV_EVIDENCE_MANIFEST),
+  releaseProfile: process.env.RELEASE_PROFILE,
+  rerunGroup: process.env.RERUN_GROUP,
+}));
+`,
+    );
+    const planInputs = {
+      children: {},
+      dockerPreflightResult: "skipped",
+      evidenceChangedPaths: reuse.changedPaths,
+      evidenceManifest: { attackerControlled: true },
+      evidencePolicy: reuse.policy,
+      evidenceReuse: true,
+      evidenceRootRunId: "99",
+      evidenceRunId: "99",
+      evidenceRunUrl: "https://example.invalid/runs/99",
+      evidenceSha: reuse.evidenceSha,
+      parentRunAttempt: 1,
+      parentRunId: "77",
+      prepareCandidateResult: "skipped",
+      rerunGroup: "all",
+      resolveTargetResult: "success",
+      trustedWorkflow: reuse.trustedWorkflow,
+      workflowRef: "release-ci/tooling",
+      workflowSha: SHA,
+    };
+    const result = spawnSync(process.execPath, [SCRIPT, "plan"], {
+      env: {
+        ...process.env,
+        FRV_EXPECTED_REUSE: JSON.stringify({
+          "--expected-changed-paths-json": JSON.stringify(reuse.changedPaths),
+          "--expected-evidence-policy": reuse.policy,
+          "--expected-evidence-sha": reuse.evidenceSha,
+          "--expected-root-run-id": "99",
+          "--expected-selected-run-id": "99",
+          "--expected-target-sha": TARGET_SHA,
+          "--trusted-workflow-full-ref": reuse.trustedWorkflow.fullRef,
+          "--trusted-workflow-ref": reuse.trustedWorkflow.ref,
+          "--trusted-workflow-sha": reuse.trustedWorkflow.sha,
+          "--validate-run": "99",
+        }),
+        FRV_EVIDENCE_MANIFEST: JSON.stringify(evidenceManifest()),
+        FRV_REUSED_CHILDREN: JSON.stringify(reusedEvidenceChildren()),
+        FRV_VALIDATOR_ARGS: validatorArgs,
+        FULL_RELEASE_EXECUTION_PLAN_PATH: output,
+        FULL_RELEASE_PLAN_INPUTS_JSON: JSON.stringify(planInputs),
+        GITHUB_REF_NAME: "release-ci/tooling",
+        GITHUB_REPOSITORY: "openclaw/openclaw",
+        GITHUB_RUN_ATTEMPT: "1",
+        GITHUB_RUN_ID: "77",
+        GITHUB_SHA: SHA,
+        OPENCLAW_RELEASE_CI_SUMMARY_VALIDATOR: validator,
+        RELEASE_PROFILE: "stable",
+        RERUN_GROUP: "all",
+        TARGET_SHA,
+      },
+      encoding: "utf8",
+      timeout: 10_000,
+    });
+    expect(result.status, result.stderr).toBe(0);
+    expect(JSON.parse(readFileSync(output, "utf8"))).toMatchObject({
+      children: [
+        expect.objectContaining({ key: "normalCi", runId: "101", source: "reused" }),
+        expect.objectContaining({ key: "pluginPrerelease", runId: "202", source: "reused" }),
+        expect.objectContaining({ key: "releaseChecks", runId: "303", source: "reused" }),
+        expect.objectContaining({ key: "npmTelegram", selected: false }),
+        expect.objectContaining({ key: "productPerformance", runId: "505", source: "reused" }),
+      ],
+      evidenceReuse: {
+        changedPaths: reuse.changedPaths,
+        evidenceSha: reuse.evidenceSha,
+        policy: reuse.policy,
+        requested: true,
+        rootRunId: "99",
+        runUrl: "https://example.invalid/runs/99",
+        selectedRunId: "99",
+        sourceManifest: evidenceManifest(),
+      },
+      trustedWorkflow: reuse.trustedWorkflow,
+    });
+    expect(JSON.parse(readFileSync(validatorArgs, "utf8"))).toContain("--expected-selected-run-id");
+  });
+
+  it("blocks Decision when canonical evidence manifest changes after planning", () => {
+    const root = mkdtempSync(join(tmpdir(), "frv-reuse-manifest-mismatch-"));
+    const output = join(root, "decision.json");
+    const executionPlanPath = join(root, "plan.json");
+    const gh = join(root, "gh");
+    const validator = join(root, "validator.mjs");
+    const sealedPlan = executionPlan(
+      { rerunGroup: "ci" },
+      {
+        evidenceReuse: {
+          changedPaths: [],
+          evidenceSha: TARGET_SHA,
+          policy: "exact-target-full-validation-v1",
+          requested: true,
+          rootRunId: "99",
+          runUrl: "https://example.invalid/runs/99",
+          selectedRunId: "99",
+          sourceManifest: evidenceManifest(),
+        },
+      },
+    );
+    writeFileSync(executionPlanPath, JSON.stringify(sealedPlan));
+    writeFileSync(
+      gh,
+      `#!/bin/sh
+case "$*" in
+  *"/jobs?"*) exit 0 ;;
+esac
+printf '%s\\n' '{"id":101,"event":"workflow_dispatch","path":".github/workflows/ci.yml@refs/heads/release-ci/tooling","display_title":"CI full-release-validation-77-1-ci","head_branch":"release-ci/tooling","head_sha":"${SHA}","run_attempt":1,"status":"completed","conclusion":"success","created_at":"2026-08-21T00:00:00Z","updated_at":"2026-08-21T00:01:00Z","html_url":"https://example.invalid/runs/101"}'
+`,
+    );
+    chmodSync(gh, 0o755);
+    writeFileSync(
+      validator,
+      `console.log(JSON.stringify({
+  children: ${JSON.stringify(reusedEvidenceChildren())},
+  manifest: {runAttempt: 1, runId: "99", targetSha: "${"c".repeat(40)}"},
+  releaseProfile: "stable",
+  rerunGroup: "ci"
+}));\n`,
+    );
+    const result = spawnSync(process.execPath, [SCRIPT, "decision"], {
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        FAIL_FAST: "false",
+        FULL_RELEASE_EXECUTION_PLAN_PATH: executionPlanPath,
+        FULL_RELEASE_STATE_PATH: output,
+        GITHUB_REF_NAME: "release-ci/tooling",
+        GITHUB_REPOSITORY: "openclaw/openclaw",
+        GITHUB_RUN_ATTEMPT: "2",
+        GITHUB_RUN_ID: "77",
+        GITHUB_SHA: SHA,
+        OPENCLAW_RELEASE_CI_SUMMARY_VALIDATOR: validator,
+        PATH: `${root}:${process.env.PATH}`,
+        RELEASE_PROFILE: "stable",
+        RERUN_GROUP: "ci",
+        TARGET_SHA,
+      },
+      timeout: 10_000,
+    });
+    expect(result.status, result.stderr).toBe(1);
+    expect(JSON.parse(readFileSync(output, "utf8")).blockers).toContainEqual(
+      expect.objectContaining({
+        kind: "provenance_mismatch",
+        message: "revalidated evidence source manifest differs from the immutable plan",
+      }),
+    );
+  });
+
+  it("validates a generated manifest against its immutable execution plan", () => {
+    const root = mkdtempSync(join(tmpdir(), "frv-generated-manifest-"));
+    const executionPlanPath = join(root, "plan.json");
+    const manifestPath = join(root, "manifest.json");
+    const sealedPlan = executionPlan({ rerunGroup: "ci" });
+    writeFileSync(executionPlanPath, JSON.stringify(sealedPlan));
+    writeFileSync(manifestPath, JSON.stringify(generatedManifest(sealedPlan)));
+    const env = {
+      ...process.env,
+      GITHUB_REF_NAME: "release-ci/tooling",
+      GITHUB_RUN_ATTEMPT: "2",
+      GITHUB_RUN_ID: "77",
+      GITHUB_SHA: SHA,
+      RELEASE_EXECUTION_PLAN_PATH: executionPlanPath,
+      RELEASE_PROFILE: "stable",
+      RELEASE_VALIDATION_MANIFEST_PATH: manifestPath,
+      RERUN_GROUP: "ci",
+      TARGET_SHA,
+    };
+    const valid = spawnSync(process.execPath, [SCRIPT, "validate-manifest"], {
+      encoding: "utf8",
+      env,
+      timeout: 10_000,
+    });
+    expect(valid.status, valid.stderr).toBe(0);
+    writeFileSync(
+      manifestPath,
+      JSON.stringify({ ...generatedManifest(sealedPlan), sourceParentRunAttempt: 2 }),
+    );
+    const invalid = spawnSync(process.execPath, [SCRIPT, "validate-manifest"], {
+      encoding: "utf8",
+      env,
+      timeout: 10_000,
+    });
+    expect(invalid.status).toBe(2);
+    expect(invalid.stderr).toContain(
+      "release validation manifest differs from the immutable execution plan",
+    );
+  });
+
+  it.each([
+    {
+      mutate: (manifest: Record<string, any>) => {
+        manifest.childRuns.normalCi = "999";
+      },
+      name: "wrong selected child",
+      planReuse: false,
+    },
+    {
+      mutate: (manifest: Record<string, any>) => {
+        manifest.childRuns.releaseChecks = "303";
+      },
+      name: "nonempty unselected child",
+      planReuse: false,
+    },
+    {
+      mutate: (manifest: Record<string, any>) => {
+        manifest.evidenceReuse.selectedRunId = "100";
+      },
+      name: "wrong evidence reuse tuple",
+      planReuse: true,
+    },
+  ])("rejects a generated manifest with $name", ({ mutate, planReuse }) => {
+    const root = mkdtempSync(join(tmpdir(), "frv-invalid-generated-manifest-"));
+    const executionPlanPath = join(root, "plan.json");
+    const manifestPath = join(root, "manifest.json");
+    const reuse = {
+      changedPaths: [],
+      evidenceSha: TARGET_SHA,
+      policy: "exact-target-full-validation-v1",
+      requested: true,
+      rootRunId: "99",
+      runUrl: "https://example.invalid/runs/99",
+      selectedRunId: "99",
+      sourceManifest: evidenceManifest(),
+    };
+    const sealedPlan = executionPlan(
+      { rerunGroup: "ci" },
+      planReuse ? { evidenceReuse: reuse } : {},
+    );
+    const manifest = generatedManifest(sealedPlan);
+    if (planReuse) {
+      manifest.evidenceReuse = {
+        changedPaths: reuse.changedPaths,
+        evidenceSha: reuse.evidenceSha,
+        policy: reuse.policy,
+        runId: reuse.rootRunId,
+        selectedRunId: reuse.selectedRunId,
+      };
+    }
+    mutate(manifest);
+    writeFileSync(executionPlanPath, JSON.stringify(sealedPlan));
+    writeFileSync(manifestPath, JSON.stringify(manifest));
+    const result = spawnSync(process.execPath, [SCRIPT, "validate-manifest"], {
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        GITHUB_REF_NAME: "release-ci/tooling",
+        GITHUB_RUN_ATTEMPT: "2",
+        GITHUB_RUN_ID: "77",
+        GITHUB_SHA: SHA,
+        RELEASE_EXECUTION_PLAN_PATH: executionPlanPath,
+        RELEASE_PROFILE: "stable",
+        RELEASE_VALIDATION_MANIFEST_PATH: manifestPath,
+        RERUN_GROUP: "ci",
+        TARGET_SHA,
+      },
+      timeout: 10_000,
+    });
+    expect(result.status).toBe(2);
+    expect(result.stderr).toContain(
+      "release validation manifest differs from the immutable execution plan",
+    );
+  });
+
+  it("persists a classified plan that Release Decision can consume after reuse rejection", () => {
+    const root = mkdtempSync(join(tmpdir(), "frv-classified-plan-"));
+    const output = join(root, "full-release-execution-plan.json");
+    const decisionOutput = join(root, "full-release-decision.json");
+    const validator = join(root, "release-evidence-validator.mjs");
+    writeFileSync(
+      validator,
+      'console.error("sealed reuse selection rejected"); process.exit(1);\n',
+    );
+    const planInputs = {
+      children: {},
+      dockerPreflightResult: "skipped",
+      evidenceChangedPaths: [],
+      evidencePolicy: "exact-target-full-validation-v1",
+      evidenceReuse: true,
+      evidenceRootRunId: "99",
+      evidenceRunId: "99",
+      evidenceRunUrl: "https://example.invalid/runs/99",
+      evidenceSha: TARGET_SHA,
+      parentRunAttempt: 1,
+      parentRunId: "77",
+      prepareCandidateResult: "skipped",
+      rerunGroup: "all",
+      resolveTargetResult: "success",
+      trustedWorkflow: TRUSTED_MAIN,
+      workflowRef: "release-ci/tooling",
+      workflowSha: SHA,
+    };
+    const baseEnv = {
+      ...process.env,
+      FULL_RELEASE_EXECUTION_PLAN_PATH: output,
+      GITHUB_REF_NAME: "release-ci/tooling",
+      GITHUB_REPOSITORY: "openclaw/openclaw",
+      GITHUB_RUN_ATTEMPT: "1",
+      GITHUB_RUN_ID: "77",
+      GITHUB_SHA: SHA,
+      OPENCLAW_RELEASE_CI_SUMMARY_VALIDATOR: validator,
+      RELEASE_PROFILE: "stable",
+      RERUN_GROUP: "all",
+      TARGET_SHA,
+    };
+    const planResult = spawnSync(process.execPath, [SCRIPT, "plan"], {
+      encoding: "utf8",
+      env: {
+        ...baseEnv,
+        FULL_RELEASE_PLAN_INPUTS_JSON: JSON.stringify(planInputs),
+      },
+      timeout: 10_000,
+    });
+    expect(planResult.status).toBe(2);
+    expect(JSON.parse(readFileSync(output, "utf8"))).toMatchObject({
+      blockers: [expect.objectContaining({ kind: "reused_evidence_invalid" })],
+      errors: [],
+    });
+
+    const decisionResult = spawnSync(process.execPath, [SCRIPT, "decision"], {
+      encoding: "utf8",
+      env: {
+        ...baseEnv,
+        FAIL_FAST: "false",
+        FULL_RELEASE_STATE_PATH: decisionOutput,
+      },
+      timeout: 10_000,
+    });
+    expect(decisionResult.status).toBe(1);
+    expect(JSON.parse(readFileSync(decisionOutput, "utf8"))).toMatchObject({
+      state: "blocked_complete",
+    });
+    expect(JSON.parse(readFileSync(decisionOutput, "utf8")).blockers).toEqual(
+      expect.arrayContaining([expect.objectContaining({ kind: "reused_evidence_invalid" })]),
+    );
+  });
+
+  it("adopts the immutable attempt-one plan on an attempt-two collector retry", () => {
+    const root = mkdtempSync(join(tmpdir(), "frv-plan-restore-"));
+    const output = join(root, "full-release-execution-plan.json");
+    const sealed = executionPlan({ rerunGroup: "ci" });
+    writeFileSync(output, JSON.stringify(sealed));
+    const result = spawnSync(process.execPath, [SCRIPT, "plan"], {
+      env: {
+        ...process.env,
+        FULL_RELEASE_EXECUTION_PLAN_PATH: output,
+        FULL_RELEASE_RESTORE_PLAN: "true",
+        GITHUB_REF_NAME: "release-ci/tooling",
+        GITHUB_RUN_ATTEMPT: "2",
+        GITHUB_RUN_ID: "77",
+        GITHUB_SHA: SHA,
+        RELEASE_PROFILE: "stable",
+        RERUN_GROUP: "ci",
+        TARGET_SHA,
+      },
+      encoding: "utf8",
+      timeout: 10_000,
+    });
+    expect(result.status, result.stderr).toBe(0);
+    expect(JSON.parse(readFileSync(output, "utf8"))).toMatchObject({
+      parentRunAttempt: 1,
+      sha256: sealed.sha256,
+    });
+  });
+
+  it("writes the execution plan immediately when SIGTERM interrupts a stalled reuse API", async () => {
+    const root = mkdtempSync(join(tmpdir(), "frv-plan-signal-"));
+    const gh = join(root, "gh");
+    const ghReady = join(root, "gh-ready");
+    const output = join(root, "full-release-execution-plan.json");
+    writeFileSync(gh, '#!/bin/sh\nprintf ready > "$FRV_GH_READY"\nsleep 30\n');
+    chmodSync(gh, 0o755);
+    const childProcess = spawn(process.execPath, [SCRIPT, "plan"], {
+      env: {
+        ...process.env,
+        EVIDENCE_CHANGED_PATHS: "[]",
+        FRV_GH_READY: ghReady,
+        FULL_RELEASE_EXECUTION_PLAN_PATH: output,
+        FULL_RELEASE_PLAN_INPUTS_JSON: JSON.stringify({
+          children: { normalCi: { result: "skipped", runAttempt: "", runId: "" } },
+          dockerPreflightResult: "skipped",
+          evidenceChangedPaths: [],
+          evidencePolicy: "exact-target-full-validation-v1",
+          evidenceReuse: true,
+          evidenceRootRunId: "99",
+          evidenceRunId: "99",
+          evidenceRunUrl: "https://example.invalid/runs/99",
+          evidenceSha: TARGET_SHA,
+          parentRunAttempt: 1,
+          parentRunId: "77",
+          prepareCandidateResult: "skipped",
+          rerunGroup: "ci",
+          resolveTargetResult: "success",
+          trustedWorkflow: TRUSTED_MAIN,
+          workflowRef: "release-ci/tooling",
+          workflowSha: SHA,
+        }),
+        GITHUB_REF_NAME: "release-ci/tooling",
+        GITHUB_REPOSITORY: "openclaw/openclaw",
+        GITHUB_RUN_ATTEMPT: "1",
+        GITHUB_RUN_ID: "77",
+        GITHUB_SHA: SHA,
+        PATH: `${root}:${process.env.PATH}`,
+        RELEASE_PROFILE: "stable",
+        RERUN_GROUP: "ci",
+        TARGET_SHA,
+      },
+      stdio: "ignore",
+    });
+    await waitForFile(ghReady, 5_000);
+    const exitPromise = waitForChildClose(childProcess);
+    const started = Date.now();
+    childProcess.kill("SIGTERM");
+    await exitPromise;
+    expect(Date.now() - started).toBeLessThan(2_000);
+    expect(JSON.parse(readFileSync(output, "utf8"))).toMatchObject({
+      errors: [expect.objectContaining({ kind: "collector_cancelled" })],
+      parentRunAttempt: 1,
+    });
+  });
+
+  it("records target resolution failure even when no target SHA exists", () => {
+    const root = mkdtempSync(join(tmpdir(), "frv-state-target-failure-"));
+    const output = join(root, "decision.json");
+    const executionPlanPath = join(root, "full-release-execution-plan.json");
+    writeFileSync(
+      executionPlanPath,
+      JSON.stringify(
+        executionPlan(
+          {
+            children: { normalCi: { result: "skipped", runAttempt: "", runId: "" } },
+            dockerPreflightResult: "skipped",
+            prepareCandidateResult: "skipped",
+            rerunGroup: "ci",
+            resolveTargetResult: "failure",
+          },
+          {
+            expected: {
+              parentRunAttempt: 1,
+              parentRunId: "77",
+              targetSha: "",
+              workflowRef: "release-ci/tooling",
+              workflowSha: SHA,
+            },
+          },
+        ),
+      ),
+    );
+    const result = spawnSync(process.execPath, [SCRIPT, "decision"], {
+      env: {
+        ...process.env,
+        FAIL_FAST: "false",
+        FULL_RELEASE_EXECUTION_PLAN_PATH: executionPlanPath,
+        FULL_RELEASE_STATE_PATH: output,
+        GITHUB_REF_NAME: "release-ci/tooling",
+        GITHUB_REPOSITORY: "openclaw/openclaw",
+        GITHUB_RUN_ATTEMPT: "2",
+        GITHUB_RUN_ID: "77",
+        GITHUB_SHA: SHA,
+        RELEASE_PROFILE: "stable",
+        RERUN_GROUP: "ci",
+        TARGET_SHA: "",
+      },
+      encoding: "utf8",
+      timeout: 10_000,
+    });
+    expect(result.status, result.stderr).toBe(1);
+    const artifact = JSON.parse(readFileSync(output, "utf8"));
+    expect(artifact).toMatchObject({
+      state: "blocked_complete",
+      targetSha: "",
+    });
+    expect(artifact.blockers).toContainEqual(
+      expect.objectContaining({
+        kind: "parent_gate_failure",
+        message: expect.stringContaining("Resolve target ref"),
+      }),
+    );
+  });
+
+  it("writes an immediate terminal handoff with active identity on SIGTERM", async () => {
+    const root = mkdtempSync(join(tmpdir(), "frv-state-signal-"));
+    const gh = join(root, "gh");
+    const ghReady = join(root, "gh-ready");
+    const output = join(root, "drain.json");
+    const executionPlanPath = join(root, "full-release-execution-plan.json");
+    writeFileSync(
+      executionPlanPath,
+      JSON.stringify(
+        executionPlan({
+          children: { normalCi: { result: "success", runAttempt: 1, runId: "101" } },
+          dockerPreflightResult: "skipped",
+          prepareCandidateResult: "skipped",
+          rerunGroup: "ci",
+          resolveTargetResult: "success",
+        }),
+      ),
+    );
+    writeFileSync(
+      gh,
+      `#!/bin/sh
+printf ready > "$FRV_GH_READY"
+if [ "$1" = "api" ] && echo "$2" | grep -q '/jobs'; then
+  exit 0
+fi
+printf '%s\\n' '{"id":101,"event":"workflow_dispatch","path":".github/workflows/ci.yml@refs/heads/release-ci/tooling","display_title":"CI full-release-validation-77-1-ci","head_branch":"release-ci/tooling","head_sha":"${SHA}","run_attempt":1,"status":"in_progress","conclusion":null,"created_at":"2026-08-21T00:00:00Z","updated_at":"2026-08-21T00:01:00Z","html_url":"https://example.invalid/runs/101"}'
+`,
+    );
+    chmodSync(gh, 0o755);
+    const childProcess = spawn(process.execPath, [SCRIPT, "drain"], {
+      env: {
+        ...process.env,
+        FAIL_FAST: "false",
+        FRV_GH_READY: ghReady,
+        FULL_RELEASE_EXECUTION_PLAN_PATH: executionPlanPath,
+        FULL_RELEASE_POLL_INTERVAL_MS: "60000",
+        FULL_RELEASE_STATE_PATH: output,
+        GITHUB_REF_NAME: "release-ci/tooling",
+        GITHUB_REPOSITORY: "openclaw/openclaw",
+        GITHUB_RUN_ATTEMPT: "2",
+        GITHUB_RUN_ID: "77",
+        GITHUB_SHA: SHA,
+        PATH: `${root}:${process.env.PATH}`,
+        RELEASE_PROFILE: "stable",
+        RERUN_GROUP: "ci",
+        TARGET_SHA: "b".repeat(40),
+      },
+      stdio: "ignore",
+    });
+    await waitForFile(ghReady, 5_000);
+    const exitPromise = waitForChildClose(childProcess);
+    childProcess.kill("SIGTERM");
+    await exitPromise;
+    expect(JSON.parse(readFileSync(output, "utf8"))).toMatchObject({
+      activeRunIds: ["101"],
+      cancellation: { requested: true },
+      state: "cancelled_with_children",
+    });
+  });
+
+  it("cancels only the exact affected child and never cancels from drain", () => {
+    const root = mkdtempSync(join(tmpdir(), "frv-state-fail-fast-"));
+    const gh = join(root, "gh");
+    const calls = join(root, "calls");
+    writeFileSync(calls, "");
+    writeFileSync(
+      gh,
+      `#!/bin/sh
+printf '%s\\n' "$*" >> "$FRV_GH_CALLS"
+if [ "$1" = "run" ] && [ "$2" = "cancel" ]; then
+  exit 0
+fi
+case "$*" in
+  *"/jobs?"*)
+    case "$*" in
+      *"/101/"*) printf '%s\\n' '{"name":"test","status":"completed","conclusion":"failure","html_url":"https://example.invalid/jobs/test"}' ;;
+    esac
+    exit 0
+    ;;
+esac
+endpoint="$2"
+[ "$endpoint" = "--paginate" ] && endpoint="$3"
+run_id=$(printf '%s' "$endpoint" | sed 's#^.*/##')
+title="CI full-release-validation-77-1-ci"
+workflow="ci.yml"
+case "$run_id" in
+  202) title="Plugin Prerelease full-release-validation-77-1-plugin-prerelease"; workflow="plugin-prerelease.yml" ;;
+  303) title="OpenClaw Release Checks full-release-validation-77-1-release-checks"; workflow="openclaw-release-checks.yml" ;;
+  505) title="OpenClaw Performance full-release-validation-77-1"; workflow="openclaw-performance.yml" ;;
+esac
+status="completed"
+[ "$run_id" = 101 ] && status="$FRV_FAILED_RUN_STATUS"
+printf '{"id":%s,"event":"workflow_dispatch","path":".github/workflows/%s@refs/heads/release-ci/tooling","display_title":"%s","head_branch":"release-ci/tooling","head_sha":"${SHA}","run_attempt":1,"status":"%s","conclusion":"%s","created_at":"2026-08-21T00:00:00Z","updated_at":"2026-08-21T00:01:00Z","html_url":"https://example.invalid/runs/%s"}\\n' "$run_id" "$workflow" "$title" "$status" "$([ "$run_id" = 101 ] && echo failure || echo success)" "$run_id"
+`,
+    );
+    chmodSync(gh, 0o755);
+    const planInputs = {
+      children: {
+        normalCi: { result: "success", runAttempt: 1, runId: "101" },
+        pluginPrerelease: { result: "success", runAttempt: 1, runId: "202" },
+        productPerformance: { result: "success", runAttempt: 1, runId: "505" },
+        releaseChecks: { result: "success", runAttempt: 1, runId: "303" },
+      },
+      dockerPreflightResult: "success",
+      evidenceReuse: false,
+      parentRunAttempt: 2,
+      parentRunId: "77",
+      prepareCandidateResult: "success",
+      rerunGroup: "all",
+      resolveTargetResult: "success",
+      workflowRef: "release-ci/tooling",
+      workflowSha: SHA,
+    };
+    const executionPlanPath = join(root, "full-release-execution-plan.json");
+    writeFileSync(
+      executionPlanPath,
+      JSON.stringify(
+        executionPlan(planInputs, {
+          expected: {
+            parentRunAttempt: 1,
+            parentRunId: "77",
+            targetSha: TARGET_SHA,
+            workflowRef: "release-ci/tooling",
+            workflowSha: SHA,
+          },
+        }),
+      ),
+    );
+    const baseEnv = {
+      ...process.env,
+      FRV_GH_CALLS: calls,
+      FULL_RELEASE_EXECUTION_PLAN_PATH: executionPlanPath,
+      GITHUB_REF_NAME: "release-ci/tooling",
+      GITHUB_REPOSITORY: "openclaw/openclaw",
+      GITHUB_RUN_ATTEMPT: "2",
+      GITHUB_RUN_ID: "77",
+      GITHUB_SHA: SHA,
+      PATH: `${root}:${process.env.PATH}`,
+      RELEASE_PROFILE: "stable",
+      RERUN_GROUP: "all",
+      TARGET_SHA: "b".repeat(40),
+    };
+    const decision = spawnSync(process.execPath, [SCRIPT, "decision"], {
+      env: {
+        ...baseEnv,
+        FAIL_FAST: "true",
+        FRV_FAILED_RUN_STATUS: "in_progress",
+        FULL_RELEASE_STATE_PATH: join(root, "decision.json"),
+      },
+      encoding: "utf8",
+      timeout: 10_000,
+    });
+    expect(decision.signal, decision.stderr).toBeNull();
+    const afterDecision = readFileSync(calls, "utf8");
+    expect(afterDecision).toContain("run cancel 101");
+    expect(afterDecision).not.toContain("run cancel 202");
+    writeFileSync(calls, "");
+    const drain = spawnSync(process.execPath, [SCRIPT, "drain"], {
+      env: {
+        ...baseEnv,
+        FAIL_FAST: "false",
+        FRV_FAILED_RUN_STATUS: "completed",
+        FULL_RELEASE_STATE_PATH: join(root, "drain.json"),
+      },
+      encoding: "utf8",
+      timeout: 10_000,
+    });
+    expect(drain.signal, drain.stderr).toBeNull();
+    expect(readFileSync(calls, "utf8")).not.toContain("run cancel");
+  });
+});
diff --git a/test/scripts/openclaw-npm-extended-stable-full-validation-workflow.test.ts b/test/scripts/openclaw-npm-extended-stable-full-validation-workflow.test.ts
index 6a7396a47788..e47ea3d0e607 100644
--- a/test/scripts/openclaw-npm-extended-stable-full-validation-workflow.test.ts
+++ b/test/scripts/openclaw-npm-extended-stable-full-validation-workflow.test.ts
@@ -45,25 +45,25 @@ describe("extended-stable Full Release Validation workflow", () => {
     const childDispatches = [
       {
         job: "normal_ci",
-        step: "Dispatch and monitor CI",
+        step: "Dispatch CI",
         workflow: "ci.yml",
         target: '-f target_ref="$TARGET_SHA"',
       },
       {
         job: "plugin_prerelease",
-        step: "Dispatch and monitor plugin prerelease",
+        step: "Dispatch plugin prerelease",
         workflow: "plugin-prerelease.yml",
         target: '-f target_ref="$TARGET_SHA" -f expected_sha="$TARGET_SHA"',
       },
       {
         job: "release_checks",
-        step: "Dispatch and monitor release checks",
+        step: "Dispatch release checks",
         workflow: "openclaw-release-checks.yml",
         target: '-f expected_sha="$TARGET_SHA"',
       },
       {
         job: "performance",
-        step: "Dispatch and monitor OpenClaw Performance",
+        step: "Dispatch OpenClaw Performance",
         workflow: "openclaw-performance.yml",
         target: '-f target_ref="$TARGET_SHA"',
       },
@@ -77,9 +77,9 @@ describe("extended-stable Full Release Validation workflow", () => {
     }
 
     expect(fullValidation).toContain("PARENT_WORKFLOW_SHA: ${{ github.sha }}");
-    expect(fullValidation).toContain('if [[ "$head_sha" != "$PARENT_WORKFLOW_SHA" ]]');
+    expect(fullValidation).toContain('if [[ "$child_head_sha" != "$PARENT_WORKFLOW_SHA" ]]');
     expect(fullValidation).toContain(
-      "child run used workflow SHA ${head_sha}, expected parent workflow SHA ${PARENT_WORKFLOW_SHA}",
+      "child run used workflow SHA ${child_head_sha}, expected parent workflow SHA ${PARENT_WORKFLOW_SHA}",
     );
   });
 
diff --git a/test/scripts/package-acceptance-workflow.test.ts b/test/scripts/package-acceptance-workflow.test.ts
index fea4d2ae2270..8b21fd7741f5 100644
--- a/test/scripts/package-acceptance-workflow.test.ts
+++ b/test/scripts/package-acceptance-workflow.test.ts
@@ -62,7 +62,7 @@ const FULL_RELEASE_CHILD_DISPATCHES = [
     kind: "ci",
     nonceSuffix: "-ci",
     runName: "CI",
-    stepName: "Dispatch and monitor CI",
+    stepName: "Dispatch CI",
     workflow: "ci.yml",
   },
   {
@@ -70,7 +70,7 @@ const FULL_RELEASE_CHILD_DISPATCHES = [
     kind: "plugin-prerelease",
     nonceSuffix: "-plugin-prerelease",
     runName: "Plugin Prerelease",
-    stepName: "Dispatch and monitor plugin prerelease",
+    stepName: "Dispatch plugin prerelease",
     workflow: "plugin-prerelease.yml",
   },
   {
@@ -78,7 +78,7 @@ const FULL_RELEASE_CHILD_DISPATCHES = [
     kind: "release-checks",
     nonceSuffix: "-release-checks",
     runName: "OpenClaw Release Checks",
-    stepName: "Dispatch and monitor release checks",
+    stepName: "Dispatch release checks",
     workflow: "openclaw-release-checks.yml",
   },
   {
@@ -86,7 +86,7 @@ const FULL_RELEASE_CHILD_DISPATCHES = [
     kind: "npm-telegram",
     nonceSuffix: "-npm-telegram",
     runName: "NPM Telegram Beta E2E",
-    stepName: "Dispatch and monitor npm Telegram E2E",
+    stepName: "Dispatch npm Telegram E2E",
     workflow: "npm-telegram-beta-e2e.yml",
   },
   {
@@ -94,7 +94,7 @@ const FULL_RELEASE_CHILD_DISPATCHES = [
     kind: "performance",
     nonceSuffix: "",
     runName: "OpenClaw Performance",
-    stepName: "Dispatch and monitor OpenClaw Performance",
+    stepName: "Dispatch OpenClaw Performance",
     workflow: "openclaw-performance.yml",
   },
 ] as const;
@@ -588,6 +588,7 @@ if (args[0] === "workflow" && args[1] === "run") {
     html_url: url,
     id: Number(env.MOCK_GH_RUN_ID),
     path: env.MOCK_GH_RUN_PATH,
+    run_attempt: Number(env.MOCK_GH_RUN_ATTEMPT),
     status: nextStatus(),
     workflow_id: Number(env.MOCK_GH_RUN_WORKFLOW_ID),
   }));
@@ -708,6 +709,7 @@ exit 0
         stepEnv.CHILD_WORKFLOW_REF,
       MOCK_GH_RUN_ID: "101",
       MOCK_GH_RUN_PATH: `.github/workflows/${child.workflow}`,
+      MOCK_GH_RUN_ATTEMPT: "1",
       MOCK_GH_RUN_TITLE: `${child.runName} full-release-validation-77-2${child.nonceSuffix}`,
       MOCK_GH_RUN_WORKFLOW_ID: "789",
       MOCK_GH_STATUSES: '["completed"]',
@@ -2774,7 +2776,7 @@ describe("package acceptance workflow", () => {
     const releaseChecksWorkflow = readFileSync(RELEASE_CHECKS_WORKFLOW, "utf8");
     const performanceJob = workflowStep(
       workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, "performance"),
-      "Dispatch and monitor OpenClaw Performance",
+      "Dispatch OpenClaw Performance",
     ).run;
 
     expect(workflow).toContain("TARGET_SHA: ${{ needs.resolve_target.outputs.sha }}");
@@ -2798,14 +2800,14 @@ describe("package acceptance workflow", () => {
     expect(releaseChecksWorkflow).toContain(
       "codex_plugin_spec: ${{ needs.resolve_target.outputs.codex_plugin_spec }}",
     );
-    expect(workflow).toContain("--json status,conclusion,url,attempt,headSha,jobs");
+    expect(workflow).toContain("full-release-validation-state.mjs verify");
     expect(workflow).toContain(
       'gh_with_retry api "repos/${GITHUB_REPOSITORY}/commits/${encoded_workflow_ref}" --jq .sha',
     );
     expect(workflow).toContain(
       "Child workflow ref ${CHILD_WORKFLOW_REF} moved to ${current_workflow_sha}, expected ${PARENT_WORKFLOW_SHA}; refusing dispatch.",
     );
-    expect(workflow).toContain('if [[ "$head_sha" != "$PARENT_WORKFLOW_SHA" ]]; then');
+    expect(workflow).toContain('if [[ "$child_head_sha" != "$PARENT_WORKFLOW_SHA" ]]; then');
     expect(workflow).toContain('gh workflow run "$workflow" --ref "$CHILD_WORKFLOW_REF" "$@" 2>&1');
     expect(performanceJob).toContain(
       'dispatch_id="full-release-validation-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"',
@@ -2821,12 +2823,11 @@ describe("package acceptance workflow", () => {
       "did not return an Actions run URL; refusing to guess from recent workflow_dispatch runs",
     );
     expect(workflow).toContain(
-      "child run used workflow SHA ${head_sha}, expected parent workflow SHA ${PARENT_WORKFLOW_SHA}",
+      "full-release-decision-${{ github.run_id }}-${{ github.run_attempt }}",
     );
     expect(workflow).toContain(
-      "Use the SHA-pinned release helper when a moving branch cannot stay fixed",
+      "full-release-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}",
     );
-    expect(workflow).toContain("| Child | Result | Minutes | Head SHA | Run |");
     expect(releaseChecksWorkflow).toContain("refs/heads/release-ci/[0-9a-f]{12}-[0-9]+");
     expect(releaseChecksWorkflow).toContain(
       "source: ${{ (needs.resolve_target.outputs.package_acceptance_package_spec != '' || needs.resolve_target.outputs.release_package_spec != '') && 'npm' || 'artifact' }}",
@@ -2840,11 +2841,11 @@ describe("package acceptance workflow", () => {
     const workflow = readFileSync(FULL_RELEASE_VALIDATION_WORKFLOW, "utf8");
     const performanceStep = workflowStep(
       workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, "performance"),
-      "Dispatch and monitor OpenClaw Performance",
+      "Dispatch OpenClaw Performance",
     );
     const summaryStep = workflowStep(
       workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, "summary"),
-      "Verify child workflow results",
+      "Verify exact release state artifacts",
     );
 
     expect(performanceStep.env?.RELEASE_PROFILE).toBe("${{ inputs.release_profile }}");
@@ -2854,13 +2855,9 @@ describe("package acceptance workflow", () => {
       "fail_on_regression=false",
       '-f fail_on_regression="$fail_on_regression"',
       "Release impact: advisory",
-      "advisory for beta",
     ]);
     expect(summaryStep.env?.RELEASE_PROFILE).toBe("${{ inputs.release_profile }}");
-    expectTextToIncludeAll(summaryStep.run, [
-      '[[ "$RELEASE_PROFILE" == "beta" ]] && performance_advisory=1',
-      'check_child "product_performance" "$PERFORMANCE_RUN_ID" "$performance_required" "$performance_advisory"',
-    ]);
+    expect(summaryStep.run).toBe("node scripts/full-release-validation-state.mjs verify");
     expect(workflow).toContain('performanceBlocking: ($releaseProfile != "beta")');
     expect(workflow).toContain('blocking: ($releaseProfile != "beta")');
   });
@@ -2885,472 +2882,192 @@ describe("package acceptance workflow", () => {
     ]);
   });
 
-  it("keeps child-job fail-fast polling best-effort", () => {
-    for (const child of FULL_RELEASE_CHILD_DISPATCHES.slice(0, 3)) {
-      const dispatch = workflowStep(
-        workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, child.jobName),
-        child.stepName,
-      );
-      expect(dispatch.env?.CHILD_WORKFLOW_KIND).toBe(child.kind);
-      expect(dispatch.run).toContain("continuing with authoritative workflow conclusion.");
-    }
-  });
-
-  it("adopts exact full-release child runs without retrying ambiguous dispatch posts", () => {
+  it("dispatches exact child identities without owning child completion", () => {
     const dispatchScripts = FULL_RELEASE_CHILD_DISPATCHES.map((child) => {
       const job = workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, child.jobName);
       const step = workflowStep(job, child.stepName);
       expect(step.env?.CHILD_WORKFLOW_KIND).toBe(child.kind);
+      expect(job["timeout-minutes"]).toBe(15);
+      expect(job.outputs).toMatchObject({
+        run_attempt: "${{ steps.dispatch.outputs.run_attempt }}",
+        run_id: "${{ steps.dispatch.outputs.run_id }}",
+        url: "${{ steps.dispatch.outputs.url }}",
+      });
       return step.run ?? "";
     });
     expect(new Set(dispatchScripts).size).toBe(1);
-
     for (const script of dispatchScripts) {
       expect(script.match(/gh workflow run/gu)).toHaveLength(1);
-      expect(script).not.toContain("gh_with_retry workflow run");
       expectTextToIncludeAll(script, [
         "The dispatch POST is one-shot",
-        'encoded_workflow_ref="$(jq -rn --arg value "$CHILD_WORKFLOW_REF"',
-        'gh_with_retry api "repos/${GITHUB_REPOSITORY}/commits/${encoded_workflow_ref}" --jq .sha',
-        '"$current_workflow_sha" != "$PARENT_WORKFLOW_SHA"',
-        "refusing dispatch.",
-        "set +e",
-        "dispatch_status=$?",
-        'if [[ "$dispatch_status" -ne 0 && ! "$dispatch_output" =~ $GH_TRANSIENT_SERVER_OR_NETWORK_PATTERN ]]',
-        "dispatch failed with non-ambiguous status ${dispatch_status}; refusing adoption polling.",
-        'sed -nE "s#^https://github[.]com/${GITHUB_REPOSITORY}/actions/runs/([0-9]+)\\$#\\1#p"',
         'validate_child_run "$run_id"',
-        'DISPATCH_RUN_NAME="$dispatch_run_name" CHILD_WORKFLOW_REF="$CHILD_WORKFLOW_REF"',
-        ".display_title == env.DISPATCH_RUN_NAME and .head_branch == env.CHILD_WORKFLOW_REF",
-        "Multiple runs matched ${dispatch_run_name}; refusing to guess.",
-        "The dispatch was not retried to avoid creating a duplicate child.",
-        "adopted exact run ${run_id}",
+        'child_run_attempt="$(jq -r \'.run_attempt // ""\' <<< "$run_json")"',
+        'echo "run_id=${run_id}" >> "$GITHUB_OUTPUT"',
+        'echo "run_attempt=${child_run_attempt}" >> "$GITHUB_OUTPUT"',
+        'echo "url=${url}" >> "$GITHUB_OUTPUT"',
       ]);
-      expect(script.indexOf("dispatch failed with non-ambiguous status")).toBeLessThan(
-        script.indexOf('run_id=""'),
-      );
+      expect(script).not.toContain("while true");
+      expect(script).not.toContain("gh run cancel");
+      expect(script).not.toContain("fail_fast_failed_jobs");
     }
-
-    const parsedWorkflow = readWorkflow(FULL_RELEASE_VALIDATION_WORKFLOW);
-    const transientPattern = parsedWorkflow.env?.GH_TRANSIENT_SERVER_OR_NETWORK_PATTERN;
-    expect(transientPattern).toBeDefined();
-    const transientError = new RegExp(transientPattern ?? "", "u");
-    for (const message of [
-      "could not create workflow dispatch event: HTTP 500: Failed to run workflow dispatch",
-      "gh: HTTP 502",
-      "500 Internal Server Error",
-      "invalid character '<' looking for beginning of value",
-      "error connecting to api.github.com",
-      "context deadline exceeded",
-      "read: connection reset by peer",
-      "connect: connection refused",
-      "net/http: TLS handshake timeout",
-      "read: i/o timeout",
-      "network is unreachable",
-      "unexpected EOF",
-      'Post "https://api.github.com/repos/openclaw/openclaw/actions/workflows/ci.yml/dispatches": EOF',
-      "EOF",
-      "ETIMEDOUT",
-      "ECONNRESET",
-      "EAI_AGAIN",
-    ]) {
-      expect(transientError.test(message), message).toBe(true);
-    }
-    for (const message of [
-      "HTTP 400: Bad Request",
-      "HTTP 401: Bad credentials",
-      "HTTP 403: Resource not accessible by integration",
-      "HTTP 404: workflow not found",
-      "HTTP 422: Validation Failed",
-      "HTTP 429: too many requests",
-      "unknown flag --field",
-      "EOFError while parsing local input",
-    ]) {
-      expect(transientError.test(message), message).toBe(false);
-    }
-
-    const summaryScript =
-      workflowStep(
-        workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, "summary"),
-        "Verify child workflow results",
-      ).run ?? "";
-    for (const script of [...dispatchScripts, summaryScript]) {
-      expect(script.match(/gh_with_retry\(\)/gu)).toHaveLength(1);
-      expectTextToIncludeAll(script, [
-        '"$output" == *"HTTP 429"*',
-        '"$output" == *"abuse detection"*',
-        '"$output" =~ $GH_TRANSIENT_SERVER_OR_NETWORK_PATTERN',
-        'return "$status"',
-      ]);
-    }
-
-    const workflow = readFileSync(FULL_RELEASE_VALIDATION_WORKFLOW, "utf8");
-    const retryCalls = workflow.split("\n").filter((line) => line.includes("gh_with_retry "));
-    expect(retryCalls.length).toBeGreaterThan(0);
-    for (const call of retryCalls) {
-      expect(call).toMatch(/gh_with_retry (api|run view)/u);
-    }
-    expect(workflow).not.toMatch(/gh_with_retry (workflow run|run cancel)/u);
-    expectTextToIncludeAll(workflow, [
-      'dispatch_id="full-release-validation-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-ci"',
-      'dispatch_id="full-release-validation-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-plugin-prerelease"',
-      'dispatch_id="full-release-validation-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-release-checks"',
-      'dispatch_id="full-release-validation-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-npm-telegram"',
-      'args+=(-f dispatch_id="$dispatch_id")',
-    ]);
-    expect(readFileSync(".github/workflows/ci.yml", "utf8")).toContain(
-      "format('CI {0}', inputs.dispatch_id)",
-    );
-    expect(readFileSync(".github/workflows/plugin-prerelease.yml", "utf8")).toContain(
-      "format('Plugin Prerelease {0}', inputs.dispatch_id)",
-    );
-    expect(readFileSync(RELEASE_CHECKS_WORKFLOW, "utf8")).toContain(
-      "format('OpenClaw Release Checks {0}', inputs.dispatch_id)",
-    );
-    expect(readFileSync(NPM_TELEGRAM_WORKFLOW, "utf8")).toContain(
-      "format('NPM Telegram Beta E2E {0}', inputs.dispatch_id)",
-    );
-    expect(readWorkflow(PLUGIN_PRERELEASE_WORKFLOW).concurrency?.group).toBe(
-      "plugin-prerelease-${{ inputs.target_ref }}-${{ github.sha }}",
-    );
-    expect(readWorkflow(RELEASE_CHECKS_WORKFLOW).concurrency?.group).toBe(
-      "openclaw-release-checks-${{ inputs.expected_sha || inputs.ref }}-${{ github.sha }}-${{ inputs.rerun_group }}",
-    );
   });
 
   it.each(FULL_RELEASE_CHILD_DISPATCHES)(
-    "adopts and validates the run URL returned for $jobName without listing runs",
+    "adopts and validates the exact $jobName run without waiting for terminal status",
     (child) => {
       const { calls, result } = runFullReleaseChildDispatch(child, {
         MOCK_GH_DISPATCH_OUTPUT: "https://github.com/openclaw/openclaw/actions/runs/101",
+        MOCK_GH_STATUSES: '["in_progress"]',
       });
 
       expect(result.status, `${result.stdout}\n${result.stderr}`).toBe(0);
       expect(calls.filter(({ args }) => args[0] === "workflow")).toHaveLength(1);
-      expect(
-        calls.filter(({ args }) =>
-          args.some((value) => value.includes("/actions/workflows/") && value.endsWith("/runs")),
-        ),
-      ).toHaveLength(0);
-      expect(
-        calls.some(({ args }) => args.some((value) => value.endsWith("/actions/runs/101"))),
-      ).toBe(true);
       expect(calls.filter(({ args }) => args[0] === "run" && args[1] === "cancel")).toHaveLength(0);
+      expect(result.stdout).toContain("Dispatched");
     },
   );
 
-  it("recovers by exact name when a successful dispatch returns no run URL", () => {
+  it("recovers one ambiguous dispatch by exact name without reposting", () => {
     const { calls, result } = runFullReleaseChildDispatch(FULL_RELEASE_CHILD_DISPATCHES[0], {
-      MOCK_GH_DISPATCH_OUTPUT: "",
+      MOCK_GH_DISPATCH_ERROR: "HTTP 500: Failed to run workflow dispatch",
     });
 
     expect(result.status, `${result.stdout}\n${result.stderr}`).toBe(0);
     expect(calls.filter(({ args }) => args[0] === "workflow")).toHaveLength(1);
-    expect(
-      calls.filter(({ args }) =>
-        args.some((value) => value.includes("/actions/workflows/") && value.endsWith("/runs")),
-      ),
-    ).toHaveLength(1);
+    expect(calls.some(({ args }) => args.includes("-X"))).toBe(true);
+    expect(result.stderr).toContain("adopted exact run 101");
   });
 
-  it.each([
-    ["workflow", { MOCK_GH_RUN_WORKFLOW_ID: "790" }],
-    ["title", { MOCK_GH_RUN_TITLE: "Unrelated workflow run" }],
-    ["head branch", { MOCK_GH_RUN_HEAD_BRANCH: "other" }],
-    ["event", { MOCK_GH_RUN_EVENT: "push" }],
-  ] as const)("refuses a returned run URL with the wrong %s", (label, overrides) => {
-    const { calls, result } = runFullReleaseChildDispatch(FULL_RELEASE_CHILD_DISPATCHES[0], {
+  it("keeps dispatch provenance failures separate from cancellation policy", () => {
+    const moved = runFullReleaseChildDispatch(FULL_RELEASE_CHILD_DISPATCHES[0], {
+      MOCK_GH_CURRENT_SHA: "c".repeat(40),
+    });
+    expect(moved.result.status).toBe(1);
+    expect(moved.result.stderr).toContain("refusing dispatch");
+    expect(moved.calls.filter(({ args }) => args[0] === "workflow")).toHaveLength(0);
+
+    const mismatched = runFullReleaseChildDispatch(FULL_RELEASE_CHILD_DISPATCHES[0], {
+      MOCK_GH_CHILD_SHA: "c".repeat(40),
       MOCK_GH_DISPATCH_OUTPUT: "https://github.com/openclaw/openclaw/actions/runs/101",
-      ...overrides,
     });
+    expect(mismatched.result.status).toBe(1);
+    expect(mismatched.result.stderr).toContain("expected parent workflow SHA");
+    expect(
+      mismatched.calls.filter(({ args }) => args[0] === "run" && args[1] === "cancel"),
+    ).toHaveLength(0);
+  });
 
-    expect(result.status).toBe(1);
-    expect(result.stderr).toContain(
-      label === "title"
-        ? "Refusing to adopt ci.yml run 101: run never became readable with display title"
-        : "Refusing to adopt unvalidated ci.yml run 101",
+  it("runs Release Decision and Diagnostic Drain in parallel from exact child tuples", () => {
+    const executionPlan = workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, "release_execution_plan");
+    const decision = workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, "release_decision");
+    const drain = workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, "diagnostic_drain");
+    const summary = workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, "summary");
+    const decisionStep = workflowStep(decision, "Evaluate release decision");
+    const drainStep = workflowStep(drain, "Drain child diagnostics");
+    const decisionUpload = workflowStep(decision, "Upload release decision");
+    const drainUpload = workflowStep(drain, "Upload diagnostic drain manifest");
+    const planStep = workflowStep(executionPlan, "Seal immutable release execution plan");
+    const planUpload = workflowStep(executionPlan, "Upload immutable release execution plan");
+    const manifestStep = workflowStep(summary, "Write release validation manifest");
+    const selectState = workflowStep(summary, "Select newest compatible release state artifacts");
+    const decisionDownloads = workflowStep(summary, "Download release decision attempts");
+    const drainDownloads = workflowStep(summary, "Download diagnostic drain attempts");
+
+    expect(decision.needs).toEqual(["resolve_target", "release_execution_plan"]);
+    expect(drain.needs).toEqual(["resolve_target", "release_execution_plan"]);
+    expect(decision.if).toBe("always()");
+    expect(drain.if).toBe("always()");
+    expect(decisionStep.run).toBe(drainStep.run);
+    expect(decisionStep.env).toMatchObject({
+      FAIL_FAST: "${{ inputs.fail_fast }}",
+      FULL_RELEASE_STATE_MODE: "decision",
+    });
+    expect(drainStep.env).toMatchObject({
+      FAIL_FAST: "false",
+      FULL_RELEASE_STATE_MODE: "drain",
+    });
+    expectTextToIncludeAll(decisionStep.run, [
+      'node scripts/full-release-validation-state.mjs "$FULL_RELEASE_STATE_MODE"',
+    ]);
+    expect(planStep.run).toContain("FULL_RELEASE_PLAN_INPUTS_JSON");
+    expect(planStep.env).toMatchObject({
+      EVIDENCE_CHANGED_PATHS: "${{ needs.evidence_reuse.outputs.changed_paths || '[]' }}",
+      EVIDENCE_RUN_ID: "${{ needs.evidence_reuse.outputs.evidence_run_id }}",
+      TRUSTED_WORKFLOW_JSON: "${{ needs.resolve_target.outputs.trusted_workflow_json }}",
+    });
+    expect(planStep.env).not.toHaveProperty("EVIDENCE_MANIFEST");
+    expect(planStep.run).not.toContain("EVIDENCE_MANIFEST");
+    expect(planStep.run).toContain('--arg evidenceRunId "$EVIDENCE_RUN_ID"');
+    expect(planStep.run).toContain('--argjson trustedWorkflow "$TRUSTED_WORKFLOW_JSON"');
+    expect(planUpload.if).toBe("${{ always() && github.run_attempt == 1 }}");
+    expect(planUpload.with?.name).toBe("full-release-execution-plan-${{ github.run_id }}");
+    expect(manifestStep.env).not.toHaveProperty("EVIDENCE_MANIFEST");
+    expect(manifestStep.run).toContain(
+      'EVIDENCE_MANIFEST="$(jq -c \'.evidenceReuse.sourceManifest // empty\' "$RELEASE_EXECUTION_PLAN_PATH")"',
     );
-    expect(
-      calls.some(({ args }) =>
-        args.some((value) => value.includes("/actions/workflows/") && value.endsWith("/runs")),
-      ),
-    ).toBe(false);
-    expect(calls.filter(({ args }) => args[0] === "run" && args[1] === "cancel")).toHaveLength(0);
-  });
-
-  it("refuses a nonnumeric exact-name candidate without cancellation ownership", () => {
-    const { calls, result } = runFullReleaseChildDispatch(FULL_RELEASE_CHILD_DISPATCHES[0], {
-      MOCK_GH_DISPATCH_OUTPUT: "",
-      MOCK_GH_MATCHES: '["not-a-run-id"]',
+    expect(manifestStep.run).not.toContain("needs.evidence_reuse.outputs");
+    expect(decisionUpload.with?.name).toBe(
+      "full-release-decision-${{ github.run_id }}-${{ github.run_attempt }}",
+    );
+    expect(drainUpload.with?.name).toBe(
+      "full-release-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}",
+    );
+    expect(decisionDownloads.with).toMatchObject({
+      path: "${{ runner.temp }}/full-release-decision-attempts",
+      pattern: "full-release-decision-${{ github.run_id }}-*",
     });
-
-    expect(result.status).toBe(1);
-    expect(result.stderr).toContain("Refusing to adopt invalid ci.yml run ID not-a-run-id");
-    expect(
-      calls.some(({ args }) => args.some((value) => value.endsWith("/actions/runs/not-a-run-id"))),
-    ).toBe(false);
-    expect(calls.filter(({ args }) => args[0] === "run" && args[1] === "cancel")).toHaveLength(0);
-  });
-
-  it.each(FULL_RELEASE_CHILD_DISPATCHES)(
-    "rejects moved workflow refs before dispatching $jobName",
-    (child) => {
-      const { calls, result } = runFullReleaseChildDispatch(child, {
-        MOCK_GH_CURRENT_SHA: "c".repeat(40),
-      });
-
-      expect(result.status).toBe(1);
-      expect(result.stderr).toContain("refusing dispatch.");
-      expect(calls.filter(({ args }) => args[0] === "workflow")).toHaveLength(0);
-    },
-  );
-
-  it.each(FULL_RELEASE_CHILD_DISPATCHES)(
-    "adopts the one exact $jobName child after an ambiguous dispatch without reposting",
-    (child) => {
-      const { calls, result } = runFullReleaseChildDispatch(child, {
-        MOCK_GH_DISPATCH_ERROR: "HTTP 500: Failed to run workflow dispatch",
-      });
-      const dispatchCalls = calls.filter(({ args }) => args[0] === "workflow");
-      const adoptionCall = calls.find(({ args }) => args.includes("-X"));
-
-      expect(result.status, `${result.stdout}\n${result.stderr}`).toBe(0);
-      expect(result.stderr).toContain("adopted exact run 101");
-      expect(dispatchCalls).toHaveLength(1);
-      expect(dispatchCalls[0]?.args.slice(0, 5)).toEqual([
-        "workflow",
-        "run",
-        child.workflow,
-        "--ref",
-        "main",
-      ]);
-      expect(adoptionCall).toMatchObject({
-        childWorkflowRef: "main",
-        dispatchRunName: `${child.runName} full-release-validation-77-2${child.nonceSuffix}`,
-      });
-      expect(adoptionCall?.args).toContain(
-        "[.workflow_runs[] | select(.display_title == env.DISPATCH_RUN_NAME and .head_branch == env.CHILD_WORKFLOW_REF) | .id]",
+    expect(drainDownloads.with).toMatchObject({
+      path: "${{ runner.temp }}/full-release-diagnostic-attempts",
+      pattern: "full-release-diagnostics-${{ github.run_id }}-*",
+    });
+    expect(selectState.run).toBe("node scripts/full-release-validation-state.mjs select");
+    expect(summary.needs).toEqual(expect.arrayContaining(["release_decision", "diagnostic_drain"]));
+    for (const jobId of [
+      "docker_runtime_assets_preflight",
+      "prepare_release_candidate",
+      "normal_ci",
+      "plugin_prerelease",
+      "release_checks",
+      "npm_telegram",
+      "performance",
+    ]) {
+      expect(String(workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, jobId).if)).toContain(
+        "github.run_attempt == 1",
       );
-      expect(calls.filter(({ args }) => args[0] === "run" && args[1] === "cancel")).toHaveLength(0);
-    },
-  );
-
-  it("leaves the adopted child running when the monitor receives SIGTERM", () => {
-    const { calls, result } = runFullReleaseChildDispatch(FULL_RELEASE_CHILD_DISPATCHES[0], {
-      MOCK_GH_STATUSES: '["in_progress"]',
-      MOCK_SLEEP_SIGNAL: "TERM",
-    });
-
-    expect(result.status, `${result.stdout}\n${result.stderr}`).toBeNull();
-    expect(result.signal).toBe("SIGTERM");
-    expect(calls.filter(({ args }) => args[0] === "run" && args[1] === "cancel")).toHaveLength(0);
+    }
   });
 
-  it.each(FULL_RELEASE_CHILD_DISPATCHES)(
-    "refuses duplicate exact adoption candidates for $jobName",
-    (child) => {
-      const { calls, result } = runFullReleaseChildDispatch(child, {
-        MOCK_GH_MATCHES: "[101, 102]",
-      });
+  it("builds a rerun-all manifest from sealed plan A instead of retry-B job outputs", () => {
+    const summary = workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, "summary");
+    const manifest = workflowStep(summary, "Write release validation manifest");
+    const evidenceDispatch = workflowStep(summary, "Request release evidence update");
 
-      expect(result.status).toBe(1);
-      expect(result.stderr).toContain("Multiple runs matched");
-      expect(calls.filter(({ args }) => args[0] === "workflow")).toHaveLength(1);
-      expect(calls.filter(({ args }) => args[0] === "run" && args[1] === "cancel")).toHaveLength(0);
-    },
-  );
-
-  it.each(FULL_RELEASE_CHILD_DISPATCHES)(
-    "refuses to adopt or retry a non-transient $jobName dispatch failure",
-    (child) => {
-      const { calls, result } = runFullReleaseChildDispatch(child, {
-        MOCK_GH_DISPATCH_ERROR: "HTTP 422: Validation Failed",
-      });
-
-      expect(result.status).toBe(1);
-      expect(result.stderr).toContain("refusing adoption polling");
-      expect(calls.filter(({ args }) => args[0] === "workflow")).toHaveLength(1);
-      expect(calls.some(({ args }) => args.includes("-X"))).toBe(false);
-      expect(calls.some(({ args }) => args[0] === "run" && args[1] === "cancel")).toBe(false);
-    },
-  );
-
-  it.each(FULL_RELEASE_CHILD_DISPATCHES)(
-    "cancels exactly the identified $jobName child when its workflow SHA differs",
-    (child) => {
-      const { calls, result } = runFullReleaseChildDispatch(child, {
-        MOCK_GH_CHILD_SHA: "c".repeat(40),
-        MOCK_GH_DISPATCH_OUTPUT: "https://github.com/openclaw/openclaw/actions/runs/101",
-      });
-
-      expect(result.status).toBe(1);
-      expect(result.stderr).toContain("expected parent workflow SHA");
-      expect(calls.filter(({ args }) => args[0] === "run" && args[1] === "cancel")).toEqual([
-        expect.objectContaining({ args: ["run", "cancel", "101"] }),
-      ]);
-    },
-  );
-
-  it.each(FULL_RELEASE_CHILD_DISPATCHES)(
-    "leaves the adopted $jobName child running when monitoring fails unexpectedly",
-    (child) => {
-      const { calls, result } = runFullReleaseChildDispatch(child, {
-        MOCK_GH_STATUS_ERROR: "HTTP 403: Resource not accessible by integration",
-      });
-
-      expect(result.status).toBe(1);
-      expect(result.stderr).toContain("HTTP 403");
-      expect(
-        calls.filter(({ args }) => args[0] === "run" && args[1] === "cancel"),
-        `${result.stdout}\n${result.stderr}\n${JSON.stringify(calls)}`,
-      ).toEqual([]);
-    },
-  );
-
-  it.each(FULL_RELEASE_CHILD_DISPATCHES.slice(0, 4))(
-    "cancels the exact $jobName child after its first blocking failed job",
-    (child) => {
-      const { calls, result } = runFullReleaseChildDispatch(child, {
-        FAIL_FAST: "true",
-        MOCK_GH_JOBS: JSON.stringify([
-          {
-            conclusion: "failure",
-            html_url: "https://github.com/openclaw/openclaw/actions/runs/101/job/201",
-            name: "Run package acceptance",
-            status: "completed",
-            url: "https://github.com/openclaw/openclaw/actions/runs/101/job/201",
-          },
-        ]),
-        MOCK_GH_STATUSES: JSON.stringify([
-          "in_progress",
-          "in_progress",
-          "in_progress",
-          "in_progress",
-          "in_progress",
-          "in_progress",
-          "completed",
-        ]),
-      });
-
-      expect(result.status, `${result.stdout}\n${result.stderr}`).toBe(1);
-      expect(result.stdout).toContain("has failed child jobs before the workflow completed");
-      expect(calls.filter(({ args }) => args[0] === "run" && args[1] === "cancel")).toHaveLength(1);
-    },
-  );
-
-  it("keeps CI fail-fast job lookups advisory and npm Telegram fail-closed without cancellation", () => {
-    const overrides = {
-      FAIL_FAST: "true",
-      MOCK_GH_JOBS_ERROR: "HTTP 403: Resource not accessible by integration",
-      MOCK_GH_STATUSES: JSON.stringify([
-        "in_progress",
-        "in_progress",
-        "in_progress",
-        "in_progress",
-        "in_progress",
-        "in_progress",
-        "completed",
-      ]),
-    };
-    const normalCi = runFullReleaseChildDispatch(FULL_RELEASE_CHILD_DISPATCHES[0], overrides);
-    const npmTelegram = runFullReleaseChildDispatch(FULL_RELEASE_CHILD_DISPATCHES[3], overrides);
-
-    expect(normalCi.result.status, normalCi.result.stderr).toBe(0);
-    expect(normalCi.result.stdout).toContain("continuing with authoritative workflow conclusion.");
-    expect(npmTelegram.result.status).toBe(1);
-    expect(
-      npmTelegram.calls.filter(({ args }) => args[0] === "run" && args[1] === "cancel"),
-      `${npmTelegram.result.stdout}\n${npmTelegram.result.stderr}\n${JSON.stringify(npmTelegram.calls)}`,
-    ).toEqual([]);
-  });
-
-  it.each([
-    { expectedStatus: 0, jobName: "Run QA Lab parity lane (sqlite)" },
-    { expectedStatus: 0, jobName: "Run QA Lab live Discord lane" },
-    { expectedStatus: 0, jobName: "Run repo/live E2E validation / Docker live" },
-    {
-      expectedStatus: 0,
-      jobName: "Run package acceptance / Telegram package acceptance / mock-openai",
-    },
-    { expectedStatus: 1, jobName: "Run repo/live E2E validation / Repo E2E" },
-    { expectedStatus: 1, jobName: "Run package acceptance / Verify package integrity" },
-  ])("preserves beta fail-fast ownership for $jobName", ({ expectedStatus, jobName }) => {
-    const { calls, result } = runFullReleaseChildDispatch(FULL_RELEASE_CHILD_DISPATCHES[2], {
-      FAIL_FAST: "true",
-      MOCK_GH_JOBS: JSON.stringify([
-        {
-          conclusion: "failure",
-          html_url: "https://github.com/openclaw/openclaw/actions/runs/101/job/201",
-          name: jobName,
-          status: "completed",
-        },
-      ]),
-      MOCK_GH_STATUSES: JSON.stringify([
-        "in_progress",
-        "in_progress",
-        "in_progress",
-        "in_progress",
-        "in_progress",
-        "in_progress",
-        "completed",
-      ]),
-      RELEASE_PROFILE: "beta",
-    });
-
-    expect(result.status, `${result.stdout}\n${result.stderr}`).toBe(expectedStatus);
-    expect(calls.filter(({ args }) => args[0] === "run" && args[1] === "cancel")).toHaveLength(
-      expectedStatus,
+    expect(manifest.env).not.toHaveProperty("TARGET_SHA");
+    expect(manifest.env).not.toHaveProperty("NORMAL_CI_RUN_ID");
+    expect(manifest.env).not.toHaveProperty("EVIDENCE_REUSE");
+    expectTextToIncludeAll(manifest.run, [
+      'TARGET_SHA="$(jq -r \'.targetSha\' "$RELEASE_EXECUTION_PLAN_PATH")"',
+      'NORMAL_CI_RUN_ID="$(jq -r \'.children[] | select(.key == "normalCi") | .runId\' "$RELEASE_EXECUTION_PLAN_PATH")"',
+      'EVIDENCE_RUN_ID="$(jq -r \'.evidenceReuse.selectedRunId // ""\' "$RELEASE_EXECUTION_PLAN_PATH")"',
+      'EVIDENCE_MANIFEST="$(jq -c \'.evidenceReuse.sourceManifest // empty\' "$RELEASE_EXECUTION_PLAN_PATH")"',
+      'PERFORMANCE_CONCLUSION="$(jq -r \'.children.productPerformance.conclusion // ""\' "$DIAGNOSTIC_DRAIN_PATH")"',
+    ]);
+    expect(manifest.run).not.toContain("needs.evidence_reuse.outputs");
+    expect(evidenceDispatch.run).toContain(
+      'EVIDENCE_REUSE="$(jq -r \'.evidenceReuse.requested\' "$RELEASE_EXECUTION_PLAN_PATH")"',
     );
+    expect(evidenceDispatch.env).not.toHaveProperty("EVIDENCE_REUSE");
   });
 
-  it.each([
-    { expectedStatus: 0, failOnRegression: "false", profile: "beta" },
-    { expectedStatus: 1, failOnRegression: "true", profile: "stable" },
-  ])(
-    "keeps failed product performance $profile release behavior unchanged",
-    ({ expectedStatus, failOnRegression, profile }) => {
-      const { calls, result } = runFullReleaseChildDispatch(FULL_RELEASE_CHILD_DISPATCHES[4], {
-        MOCK_GH_CONCLUSION: "failure",
-        RELEASE_PROFILE: profile,
-      });
-      const dispatch = calls.find(({ args }) => args[0] === "workflow");
+  it("pins every Full Release Validation artifact download to the canonical action", () => {
+    const workflow = readWorkflow(FULL_RELEASE_VALIDATION_WORKFLOW);
+    const downloadSteps = Object.values(workflow.jobs ?? {}).flatMap((job) =>
+      (job.steps ?? []).filter((step) => step.uses?.startsWith("actions/download-artifact@")),
+    );
 
-      expect(result.status, `${result.stdout}\n${result.stderr}`).toBe(expectedStatus);
-      expect(dispatch?.args).toContain(`fail_on_regression=${failOnRegression}`);
-      if (profile === "beta") {
-        expect(result.stdout).toContain("advisory for beta");
-      }
-    },
-  );
-
-  it.each([
-    { expectedStatus: 0, failingJob: "Run optional live-provider check" },
-    { expectedStatus: 1, failingJob: "Run package acceptance" },
-  ])("keeps Tideclaw alpha package-safety lanes blocking", ({ expectedStatus, failingJob }) => {
-    const { result } = runFullReleaseChildDispatch(FULL_RELEASE_CHILD_DISPATCHES[2], {
-      CHILD_WORKFLOW_REF: "tideclaw/alpha/2026-08-01-0000Z",
-      MOCK_GH_CONCLUSION: "failure",
-      MOCK_GH_JOBS: JSON.stringify([
-        {
-          conclusion: "success",
-          html_url: "https://github.com/openclaw/openclaw/actions/runs/101/job/201",
-          name: "Verify release checks",
-          status: "completed",
-        },
-        {
-          conclusion: "failure",
-          html_url: "https://github.com/openclaw/openclaw/actions/runs/101/job/202",
-          name: failingJob,
-          status: "completed",
-        },
-      ]),
-    });
-
-    expect(result.status, `${result.stdout}\n${result.stderr}`).toBe(expectedStatus);
-    if (expectedStatus === 0) {
-      expect(result.stdout).toContain("accepted Tideclaw alpha advisory lanes");
-    } else {
-      expect(result.stdout).toContain("package-safety Tideclaw alpha release-check lane");
+    expect(downloadSteps).toHaveLength(6);
+    for (const step of downloadSteps) {
+      expect(step.uses).toBe(DOWNLOAD_ARTIFACT_V8);
     }
   });
 
@@ -3699,11 +3416,11 @@ describe("package artifact reuse", () => {
     const prepare = workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, "prepare_release_candidate");
     const pluginDispatch = workflowStep(
       workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, "plugin_prerelease"),
-      "Dispatch and monitor plugin prerelease",
+      "Dispatch plugin prerelease",
     );
     const releaseDispatch = workflowStep(
       workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, "release_checks"),
-      "Dispatch and monitor release checks",
+      "Dispatch release checks",
     );
 
     expect(prepare.uses).toBe("./.github/workflows/openclaw-live-and-e2e-checks-reusable.yml");
@@ -3724,7 +3441,7 @@ describe("package artifact reuse", () => {
     expect(releaseDispatch.run).toContain(
       'args+=(-f candidate_artifact_json="$CANDIDATE_ARTIFACT_JSON")',
     );
-    expect(workflow).toContain("Shared release candidate preparation ended with");
+    expect(workflow).toContain("prepareCandidateResult: $prepareCandidateResult");
   });
 
   it("enables prerelease plugin companions for scheduled ref validation", () => {
@@ -5683,12 +5400,9 @@ describe("package artifact reuse", () => {
     const toolingIdentity = workflowStep(resolveTargetJob, "Resolve trusted workflow identity");
     const releaseInputValidation = workflowStep(resolveTargetJob, "Validate release inputs");
     const evidenceReuseStep = workflowStep(evidenceReuseJob, "Find reusable validation evidence");
-    const releaseChecksDispatchStep = workflowStep(
-      releaseChecksJob,
-      "Dispatch and monitor release checks",
-    );
-    const dispatchStep = workflowStep(npmTelegramJob, "Dispatch and monitor npm Telegram E2E");
-    const verificationStep = workflowStep(summaryJob, "Verify child workflow results");
+    const releaseChecksDispatchStep = workflowStep(releaseChecksJob, "Dispatch release checks");
+    const dispatchStep = workflowStep(npmTelegramJob, "Dispatch npm Telegram E2E");
+    const verificationStep = workflowStep(summaryJob, "Verify exact release state artifacts");
     const manifestStep = workflowStep(summaryJob, "Write release validation manifest");
 
     expect(workflowInputs).toMatchObject({
@@ -5744,10 +5458,8 @@ describe("package artifact reuse", () => {
     ]);
     expect(npmTelegramJob.name).toBe("Run package Telegram E2E");
     expect(npmTelegramJob.needs).toEqual(["resolve_target", "evidence_reuse"]);
-    expect(npmTelegramJob["timeout-minutes"]).toBe(
-      "${{ inputs.release_profile == 'full' && 360 || 120 }}",
-    );
-    expect(performanceJob["timeout-minutes"]).toBe(360);
+    expect(npmTelegramJob["timeout-minutes"]).toBe(15);
+    expect(performanceJob["timeout-minutes"]).toBe(15);
     expect(npmTelegramJob.if).toContain(
       'contains(fromJSON(\'["all","npm-telegram"]\'), inputs.rerun_group)',
     );
@@ -5792,7 +5504,6 @@ describe("package artifact reuse", () => {
     expect(dispatchStep.env).toEqual({
       CHILD_WORKFLOW_KIND: "npm-telegram",
       CHILD_WORKFLOW_REF: "${{ github.ref_name }}",
-      FAIL_FAST: "${{ inputs.fail_fast }}",
       GH_TOKEN: "${{ github.token }}",
       PACKAGE_SPEC: "${{ inputs.npm_telegram_package_spec || inputs.release_package_spec }}",
       PARENT_WORKFLOW_SHA: "${{ github.sha }}",
@@ -5818,17 +5529,18 @@ describe("package artifact reuse", () => {
       "allowUnreleasedChangelog: $allowUnreleasedChangelog",
     ]);
     expect(verificationStep.env).toMatchObject({
-      SKIP_PACKAGE_TELEGRAM_E2E: "${{ inputs.skip_package_telegram_e2e }}",
+      RELEASE_PROFILE: "${{ inputs.release_profile }}",
+      RERUN_GROUP: "${{ inputs.rerun_group }}",
     });
-    expect(verificationStep.run).toContain("Package Telegram E2E deferred:");
+    expect(verificationStep.run).toBe("node scripts/full-release-validation-state.mjs verify");
     expectTextToIncludeAll(dispatchStep.run, [
       'dispatch_id="full-release-validation-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-npm-telegram"',
       'dispatch_output="$(gh workflow run "$workflow" --ref "$CHILD_WORKFLOW_REF" "$@" 2>&1)"',
-      'dispatch_and_wait npm-telegram-beta-e2e.yml "$dispatch_run_name" "${args[@]}"',
+      'dispatch_child npm-telegram-beta-e2e.yml "$dispatch_run_name" "${args[@]}"',
       ".display_title == env.DISPATCH_RUN_NAME and .head_branch == env.CHILD_WORKFLOW_REF",
       "The dispatch was not retried to avoid creating a duplicate child.",
       'if [[ "$child_head_sha" != "$PARENT_WORKFLOW_SHA" ]]; then',
-      "Still waiting on ${workflow} after ${elapsed_minutes}m:",
+      'echo "run_attempt=${child_run_attempt}" >> "$GITHUB_OUTPUT"',
       '-f harness_ref="$TARGET_SHA"',
       'args=(-f package_spec="$PACKAGE_SPEC"',
       'args+=(-f scenario="$SCENARIO")',
@@ -5838,28 +5550,12 @@ describe("package artifact reuse", () => {
       '-f rerun_group="$RERUN_GROUP"',
       'args+=(-f live_suite_filter="$LIVE_SUITE_FILTER")',
       'args+=(-f cross_os_suite_filter="$CROSS_OS_SUITE_FILTER")',
-      'case "$RERUN_GROUP" in',
-      "install-smoke|cross-os|live-e2e|package|qa-parity|qa-live)",
       "cancel-in-progress: false",
-      "Verify release checks accepted Tideclaw alpha advisory lanes",
-      "release_checks_advisory_only",
-      "release_check_blocking_job",
-      'if [[ "$RERUN_GROUP" == "npm-telegram" || ( "$RERUN_GROUP" == "all"',
-      "npm_telegram_required=1",
-      "Reused evidence did not record the required npm Telegram child run.",
-      'check_child "npm_telegram" "" "$npm_telegram_required"',
-      'if [[ "$RELEASE_PROFILE" == "beta" && "$1" == "Run package acceptance / Telegram package acceptance / "* ]]; then',
-      'or (.name | startswith("Run QA Lab runtime-pair lane ("))',
-      'or .name == "Run QA Lab live Discord lane"',
-      'or (.name | startswith("Run package acceptance / Telegram package acceptance / ")))',
-      "is a package-safety Tideclaw alpha release-check lane",
-      '"Run package acceptance" | \\',
-      '"Run package acceptance / "*)',
-      'check_child "release_checks" "$RELEASE_CHECKS_RUN_ID" 1 1',
-      "gh run cancel",
+      "FULL_RELEASE_PLAN_INPUTS_JSON",
+      "full-release-validation-policy.mjs",
+      "full-release-validation-state.mjs verify",
+      'FAIL_FAST: "false"',
       "NORMAL_CI_RESULT: ${{ needs.normal_ci.result }}",
-      "Sorry. Your account was suspended",
-      'gh_with_retry run view "$run_id" --json status,conclusion,url,attempt,headSha,jobs',
     ]);
     expect(workflow).not.toContain("force-cancel");
     expect(workflow).not.toContain("workflow_ref:");
@@ -6665,21 +6361,22 @@ describe("package artifact reuse", () => {
     const summaryJob = parsedWorkflow.jobs?.summary;
     const manifestStep = workflowStep(summaryJob ?? {}, "Write release validation manifest");
 
-    expect(workflow).toContain("### Slowest jobs: ${label}");
-    expect(workflow).toContain("### Longest start delays: ${label}");
     expect(workflow).toContain("Write release validation manifest");
     expect(workflow).toContain("PERFORMANCE_RUN_ID: ${{ needs.performance.outputs.run_id }}");
     expect(workflow).toContain("Upload release validation manifest");
-    expect(workflow).toContain("Failed child detail: ${label}");
-    expect(workflow).toContain("actions/runs/${run_id}/artifacts?per_page=100");
+    expect(workflow).toContain("Download diagnostic drain attempts");
     expect(workflow).toContain("full-release-validation-${{ github.run_id }}");
-    expect(workflow).toContain("| Job | Result | Start delay minutes | Run minutes |");
-    expect(workflow).toContain(
-      'gh_with_retry api --paginate "repos/${GITHUB_REPOSITORY}/actions/runs/${run_id}/jobs?per_page=100"',
-    );
-    expect(workflow).toContain("(.started_at | ts) - (.created_at | ts)");
+    expect(workflow).toContain("full-release-diagnostic-manifest.json");
     expect(workflow).not.toContain('gh run view "$run_id" --json createdAt,jobs');
-    expect(manifestStep.env?.PERFORMANCE_RUN_ID).toBe("${{ needs.performance.outputs.run_id }}");
+    expect(manifestStep.env?.RELEASE_EXECUTION_PLAN_PATH).toContain(
+      "full-release-execution-plan.json",
+    );
+    expect(manifestStep.env?.DIAGNOSTIC_DRAIN_PATH).toContain(
+      "full-release-diagnostic-manifest.json",
+    );
+    expect(manifestStep.run).toContain(
+      `PERFORMANCE_RUN_ID="$(jq -r '.children[] | select(.key == "productPerformance") | .runId' "$RELEASE_EXECUTION_PLAN_PATH")"`,
+    );
     expect(manifestStep.run).toContain('--arg performanceRunId "$PERFORMANCE_RUN_ID"');
   });
 
@@ -7470,7 +7167,7 @@ wait_for_run plugin-clawhub-new.yml 123 "${expectedSha}" || status=$?
     expect(readFileSync(LIVE_E2E_WORKFLOW, "utf8")).toContain("live-cache attempt ${attempt}/2");
   });
 
-  it("keeps known bounded dominant child paths below parent monitors", () => {
+  it("keeps known bounded dominant child paths below the centralized drain owner", () => {
     const fullRelease = readWorkflow(FULL_RELEASE_VALIDATION_WORKFLOW);
     const pluginPrerelease = readWorkflow(PLUGIN_PRERELEASE_WORKFLOW);
     const liveE2e = readWorkflow(LIVE_E2E_WORKFLOW);
@@ -7480,6 +7177,25 @@ wait_for_run plugin-clawhub-new.yml 123 "${expectedSha}" || status=$?
     const packageAcceptance = readWorkflow(PACKAGE_ACCEPTANCE_WORKFLOW);
     const qaLive = readWorkflow(QA_LIVE_TRANSPORTS_WORKFLOW);
     const profiles = ["beta", "stable", "full"] as const;
+    const releaseDecisionTimeout = timeoutForProfile(
+      fullRelease.jobs?.release_decision?.["timeout-minutes"],
+      "beta",
+    );
+    const diagnosticDrainTimeout = timeoutForProfile(
+      fullRelease.jobs?.diagnostic_drain?.["timeout-minutes"],
+      "beta",
+    );
+    expect(releaseDecisionTimeout).toBe(720);
+    expect(diagnosticDrainTimeout).toBe(720);
+    for (const dispatchJob of [
+      "normal_ci",
+      "plugin_prerelease",
+      "release_checks",
+      "npm_telegram",
+      "performance",
+    ]) {
+      expect(fullRelease.jobs?.[dispatchJob]?.["timeout-minutes"], dispatchJob).toBe(15);
+    }
 
     const ciPreflight = workflowJob(CI_WORKFLOW, "preflight");
     const ciIos = workflowJob(CI_WORKFLOW, "ios-build");
@@ -7494,29 +7210,20 @@ wait_for_run plugin-clawhub-new.yml 123 "${expectedSha}" || status=$?
     expect(ciPath).toEqual([20, 150, 5]);
     const ciChildTimeout = ciPath.reduce((total, timeout) => total + timeout, 0);
     expect(ciChildTimeout).toBe(175);
-    const ciParentTimeout = timeoutForProfile(
-      fullRelease.jobs?.normal_ci?.["timeout-minutes"],
-      "beta",
-    );
-    expect(ciChildTimeout).toBeLessThanOrEqual(ciParentTimeout);
-    expect(ciParentTimeout - ciChildTimeout).toBeGreaterThanOrEqual(60);
+    expect(ciChildTimeout).toBeLessThanOrEqual(diagnosticDrainTimeout);
+    expect(diagnosticDrainTimeout - ciChildTimeout).toBeGreaterThanOrEqual(60);
 
     expect(liveE2e.jobs?.validate_selected_ref?.["timeout-minutes"]).toBe(30);
-    const pluginMonitorTimeout = fullRelease.jobs?.plugin_prerelease?.["timeout-minutes"];
     const pluginChildTimeouts = Object.fromEntries(
       profiles.map((profile) => [
         profile,
         pluginPrereleaseTimeoutFloor(pluginPrerelease, liveE2e, profile),
       ]),
     ) as Record<(typeof profiles)[number], number>;
-    const pluginParentTimeouts = Object.fromEntries(
-      profiles.map((profile) => [profile, timeoutForProfile(pluginMonitorTimeout, profile)]),
-    ) as Record<(typeof profiles)[number], number>;
     expect(pluginChildTimeouts).toEqual({ beta: 175, stable: 175, full: 205 });
-    expect(pluginParentTimeouts).toEqual({ beta: 240, stable: 240, full: 300 });
     for (const profile of profiles) {
       expect(
-        pluginParentTimeouts[profile] - pluginChildTimeouts[profile],
+        diagnosticDrainTimeout - pluginChildTimeouts[profile],
         `plugin-prerelease:${profile}`,
       ).toBeGreaterThanOrEqual(60);
     }
@@ -7594,7 +7301,7 @@ wait_for_run plugin-clawhub-new.yml 123 "${expectedSha}" || status=$?
     });
     const releaseChecksParent = workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, "release_checks");
     expect(releaseChecksParent["runs-on"]).toBe("blacksmith-4vcpu-ubuntu-2404");
-    expect(releaseChecksParent["timeout-minutes"]).toBe(420);
+    expect(releaseChecksParent["timeout-minutes"]).toBe(15);
     const releasePackageTimeouts = {
       beta: releasePackagePaths.beta.reduce((total, timeout) => total + timeout, 0),
       stable: releasePackagePaths.stable.reduce((total, timeout) => total + timeout, 0),
@@ -7602,8 +7309,13 @@ wait_for_run plugin-clawhub-new.yml 123 "${expectedSha}" || status=$?
     };
     expect(releasePackageTimeouts).toEqual({ beta: 310, stable: 310, full: 340 });
     for (const [profile, childTimeout] of Object.entries(releasePackageTimeouts)) {
-      expect(childTimeout, `release-package:${profile}`).toBeLessThanOrEqual(420);
-      expect(420 - childTimeout, `release-package:${profile}`).toBeGreaterThanOrEqual(60);
+      expect(childTimeout, `release-package:${profile}`).toBeLessThanOrEqual(
+        diagnosticDrainTimeout,
+      );
+      expect(
+        diagnosticDrainTimeout - childTimeout,
+        `release-package:${profile}`,
+      ).toBeGreaterThanOrEqual(60);
     }
 
     const releaseSummary = workflowJob(RELEASE_CHECKS_WORKFLOW, "summary");
@@ -7675,8 +7387,13 @@ wait_for_run plugin-clawhub-new.yml 123 "${expectedSha}" || status=$?
       ["qa-live", releaseQaLivePath],
     ] as const) {
       const childTimeout = path.reduce((total, timeout) => total + timeout, 0);
-      expect(childTimeout, `release-checks:${pathName}`).toBeLessThanOrEqual(420);
-      expect(420 - childTimeout, `release-checks:${pathName}`).toBeGreaterThanOrEqual(60);
+      expect(childTimeout, `release-checks:${pathName}`).toBeLessThanOrEqual(
+        diagnosticDrainTimeout,
+      );
+      expect(
+        diagnosticDrainTimeout - childTimeout,
+        `release-checks:${pathName}`,
+      ).toBeGreaterThanOrEqual(60);
     }
     expect(releaseCrossOsPath.reduce((total, timeout) => total + timeout, 0)).toBe(200);
     expect(releaseInstallPath.reduce((total, timeout) => total + timeout, 0)).toBe(265);
@@ -7702,24 +7419,14 @@ wait_for_run plugin-clawhub-new.yml 123 "${expectedSha}" || status=$?
       0,
     );
     expect(releaseTelegramTimeout).toBe(245);
-    expect(420 - releaseTelegramTimeout).toBeGreaterThanOrEqual(60);
+    expect(diagnosticDrainTimeout - releaseTelegramTimeout).toBeGreaterThanOrEqual(60);
 
     const npmTelegramChildTimeout = timeoutForProfile(
       workflowJob(NPM_TELEGRAM_WORKFLOW, "run_package_telegram_e2e")["timeout-minutes"],
       "beta",
     );
     expect(npmTelegramChildTimeout).toBe(60);
-    for (const profile of profiles) {
-      const parentTimeout = timeoutForProfile(
-        fullRelease.jobs?.npm_telegram?.["timeout-minutes"],
-        profile,
-      );
-      expect(parentTimeout).toBe(profile === "full" ? 360 : 120);
-      expect(
-        parentTimeout - npmTelegramChildTimeout,
-        `npm-telegram:${profile}`,
-      ).toBeGreaterThanOrEqual(60);
-    }
+    expect(diagnosticDrainTimeout - npmTelegramChildTimeout).toBeGreaterThanOrEqual(60);
 
     const performanceResolve = workflowJob(PERFORMANCE_WORKFLOW, "resolve_target");
     const performanceKova = workflowJob(PERFORMANCE_WORKFLOW, "kova");
@@ -7750,17 +7457,20 @@ wait_for_run plugin-clawhub-new.yml 123 "${expectedSha}" || status=$?
     expect(performanceArtifactPath.reduce((total, timeout) => total + timeout, 0)).toBe(255);
     expect(performancePublishPath.reduce((total, timeout) => total + timeout, 0)).toBe(280);
     const performanceParent = workflowJob(FULL_RELEASE_VALIDATION_WORKFLOW, "performance");
-    expect(performanceParent["timeout-minutes"]).toBe(360);
-    expect(
-      workflowStep(performanceParent, "Dispatch and monitor OpenClaw Performance").run,
-    ).toContain("-f publish_reports=false");
+    expect(performanceParent["timeout-minutes"]).toBe(15);
+    expect(workflowStep(performanceParent, "Dispatch OpenClaw Performance").run).toContain(
+      "-f publish_reports=false",
+    );
     for (const [pathName, path] of [
       ["artifact-only", performanceArtifactPath],
       ["publish", performancePublishPath],
     ] as const) {
       const childTimeout = path.reduce((total, timeout) => total + timeout, 0);
-      expect(childTimeout, `performance:${pathName}`).toBeLessThanOrEqual(360);
-      expect(360 - childTimeout, `performance:${pathName}`).toBeGreaterThanOrEqual(60);
+      expect(childTimeout, `performance:${pathName}`).toBeLessThanOrEqual(diagnosticDrainTimeout);
+      expect(
+        diagnosticDrainTimeout - childTimeout,
+        `performance:${pathName}`,
+      ).toBeGreaterThanOrEqual(60);
     }
 
     const prepareReleaseCandidate = workflowJob(
@@ -7787,12 +7497,11 @@ wait_for_run plugin-clawhub-new.yml 123 "${expectedSha}" || status=$?
       timeoutForProfile(liveE2e.jobs?.prepare_docker_e2e_image?.["timeout-minutes"], "full"),
       timeoutForProfile(liveE2e.jobs?.docker_e2e_image_ready?.["timeout-minutes"], "full"),
       timeoutForProfile(releaseChecksParent["timeout-minutes"], "full"),
-      timeoutForProfile(fullRelease.jobs?.summary?.["timeout-minutes"], "full"),
     ];
-    expect(fullParentPath).toEqual([10, 10, 30, 90, 5, 420, 5]);
+    expect(fullParentPath).toEqual([10, 10, 30, 90, 5, 15]);
     const fullParentTimeoutFloor = fullParentPath.reduce((total, timeout) => total + timeout, 0);
-    expect(fullParentTimeoutFloor).toBe(570);
-    expect(FULL_RELEASE_WAIT_TIMEOUT_MINUTES - fullParentTimeoutFloor).toBeGreaterThanOrEqual(60);
+    expect(fullParentTimeoutFloor).toBe(160);
+    expect(FULL_RELEASE_WAIT_TIMEOUT_MINUTES).toBe(diagnosticDrainTimeout);
   });
 
   it("bounds every direct job in nested release workflows", () => {
diff --git a/test/scripts/plugin-prerelease-test-plan.test.ts b/test/scripts/plugin-prerelease-test-plan.test.ts
index 5ef611eb5cb1..e32abf6afd91 100644
--- a/test/scripts/plugin-prerelease-test-plan.test.ts
+++ b/test/scripts/plugin-prerelease-test-plan.test.ts
@@ -11,10 +11,6 @@ import {
   assertPluginPrereleaseTestPlanComplete,
   createPluginPrereleaseTestPlan,
 } from "../../scripts/lib/plugin-prerelease-test-plan.mts";
-import {
-  pluginPrereleaseTimeoutComponents,
-  releaseTimeoutForProfile,
-} from "../helpers/release-workflow-timeouts.js";
 import { useAutoCleanupTempDirTracker } from "../helpers/temp-dir.js";
 
 const CHECKOUT_V6 = "actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10";
@@ -45,19 +41,6 @@ function readPluginPrereleaseWorkflow() {
   return parse(readFileSync(".github/workflows/plugin-prerelease.yml", "utf8"));
 }
 
-function readLiveE2eWorkflow() {
-  return parse(readFileSync(".github/workflows/openclaw-live-and-e2e-checks-reusable.yml", "utf8"));
-}
-
-function pluginPrereleaseTimeoutFloor(profile: "beta" | "stable" | "full"): number {
-  const components = pluginPrereleaseTimeoutComponents({
-    pluginPrerelease: readPluginPrereleaseWorkflow(),
-    liveE2e: readLiveE2eWorkflow(),
-    profile,
-  });
-  return Object.values(components).reduce((total, value) => total + value, 0);
-}
-
 function getDockerLane(name: string) {
   const lane = findLaneByName(name);
   if (!lane) {
@@ -387,7 +370,7 @@ describe("scripts/lib/plugin-prerelease-test-plan.mts", () => {
       (step: WorkflowStep) => step.name === "Summarize target",
     );
     const pluginDispatch = releaseWorkflow.jobs.plugin_prerelease.steps.find(
-      (step: WorkflowStep) => step.name === "Dispatch and monitor plugin prerelease",
+      (step: WorkflowStep) => step.name === "Dispatch plugin prerelease",
     );
     const evidenceReuse = releaseWorkflow.jobs.evidence_reuse.steps.find(
       (step: WorkflowStep) => step.name === "Find reusable validation evidence",
@@ -497,13 +480,13 @@ describe("scripts/lib/plugin-prerelease-test-plan.mts", () => {
       (step: WorkflowStep) => step.name === "Build plugin prerelease manifest",
     ).env;
     const normalCiScript = releaseWorkflow.jobs.normal_ci.steps.find(
-      (step: WorkflowStep) => step.name === "Dispatch and monitor CI",
+      (step: WorkflowStep) => step.name === "Dispatch CI",
     ).run;
     const pluginPrereleaseScript = releaseWorkflow.jobs.plugin_prerelease.steps.find(
-      (step: WorkflowStep) => step.name === "Dispatch and monitor plugin prerelease",
+      (step: WorkflowStep) => step.name === "Dispatch plugin prerelease",
     ).run;
     const releaseChecksStep = releaseWorkflow.jobs.release_checks.steps.find(
-      (step: WorkflowStep) => step.name === "Dispatch and monitor release checks",
+      (step: WorkflowStep) => step.name === "Dispatch release checks",
     );
     const releaseChecksScript = releaseChecksStep.run;
     const buildDistStep = workflow.jobs["build-artifacts"].steps.find(
@@ -666,9 +649,9 @@ describe("scripts/lib/plugin-prerelease-test-plan.mts", () => {
     expect(releaseChecksScript).toContain("args+=(-f allow_frozen_target_scenario_omissions=true)");
     expect(releaseWorkflowSource).toContain('--arg targetContextRef "$TARGET_CONTEXT_REF"');
     expect(releaseWorkflowSource).toContain("targetContextRef: $targetContextRef");
-    expect(normalCiScript).toContain('dispatch_and_wait ci.yml "$dispatch_run_name" "${args[@]}"');
+    expect(normalCiScript).toContain('dispatch_child ci.yml "$dispatch_run_name" "${args[@]}"');
     const normalCiDispatchCase = normalCiScript.match(/^\s*ci\)\n([\s\S]*?)^\s*;;$/mu)?.[1];
-    expect(normalCiDispatchCase).toContain('dispatch_and_wait ci.yml "$dispatch_run_name"');
+    expect(normalCiDispatchCase).toContain('dispatch_child ci.yml "$dispatch_run_name"');
     expect(normalCiDispatchCase).not.toContain("full_release_validation=true");
     expect(pluginPrereleaseScript).toContain(
       'args=(-f target_ref="$TARGET_SHA" -f expected_sha="$TARGET_SHA" -f full_release_validation=true -f dispatch_id="$dispatch_id" -f node_test_exclude_patterns_json="$PLUGIN_PRERELEASE_NODE_EXCLUDE_PATTERNS_JSON")',
@@ -677,7 +660,7 @@ describe("scripts/lib/plugin-prerelease-test-plan.mts", () => {
       'args+=(-f candidate_artifact_json="$CANDIDATE_ARTIFACT_JSON")',
     );
     expect(pluginPrereleaseScript).toContain(
-      'dispatch_and_wait plugin-prerelease.yml "$dispatch_run_name" "${args[@]}"',
+      'dispatch_child plugin-prerelease.yml "$dispatch_run_name" "${args[@]}"',
     );
     expect(pluginManifestScript).toContain("await import(");
     expect(pluginManifestScript).toContain('"./scripts/lib/plugin-prerelease-test-plan.mts"');
@@ -887,7 +870,7 @@ describe("scripts/lib/plugin-prerelease-test-plan.mts", () => {
     }
     expect(fullReleaseWorkflow.jobs.release_checks["runs-on"]).toBe("blacksmith-4vcpu-ubuntu-2404");
     expect(fullReleaseWorkflow.jobs.performance["runs-on"]).toBe("blacksmith-4vcpu-ubuntu-2404");
-    expect(fullReleaseWorkflow.jobs.normal_ci["timeout-minutes"]).toBe(240);
+    expect(fullReleaseWorkflow.jobs.normal_ci["timeout-minutes"]).toBe(15);
     expect(fullReleaseWorkflow.jobs.normal_ci.needs).toEqual(["resolve_target", "evidence_reuse"]);
     expect(fullReleaseWorkflow.jobs.normal_ci.if).toContain(
       "needs.resolve_target.result == 'success'",
@@ -896,7 +879,7 @@ describe("scripts/lib/plugin-prerelease-test-plan.mts", () => {
       "needs.evidence_reuse.outputs.reuse != 'true'",
     );
     expect(fullReleaseWorkflow.jobs.docker_runtime_assets_preflight.if).toBe(
-      "${{ always() && needs.resolve_target.result == 'success' && inputs.rerun_group == 'all' && needs.evidence_reuse.outputs.reuse != 'true' }}",
+      "${{ always() && github.run_attempt == 1 && needs.resolve_target.result == 'success' && inputs.rerun_group == 'all' && needs.evidence_reuse.outputs.reuse != 'true' }}",
     );
     expect(fullReleaseWorkflow.jobs.docker_runtime_assets_preflight["timeout-minutes"]).toBe(20);
     const dockerPreflightStep = fullReleaseWorkflow.jobs.docker_runtime_assets_preflight.steps.find(
@@ -914,33 +897,13 @@ describe("scripts/lib/plugin-prerelease-test-plan.mts", () => {
         (step: WorkflowStep) => step.name === "Build and smoke test final Docker runtime image",
       ),
     ).toBe(false);
-    const pluginMonitorTimeout = fullReleaseWorkflow.jobs.plugin_prerelease["timeout-minutes"];
-    const childTimeoutFloors = {
-      beta: pluginPrereleaseTimeoutFloor("beta"),
-      stable: pluginPrereleaseTimeoutFloor("stable"),
-      full: pluginPrereleaseTimeoutFloor("full"),
-    };
-    const parentTimeouts = {
-      beta: releaseTimeoutForProfile(pluginMonitorTimeout, "beta"),
-      stable: releaseTimeoutForProfile(pluginMonitorTimeout, "stable"),
-      full: releaseTimeoutForProfile(pluginMonitorTimeout, "full"),
-    };
-    expect(childTimeoutFloors).toEqual({ beta: 175, stable: 175, full: 205 });
-    expect(parentTimeouts).toEqual({ beta: 240, stable: 240, full: 300 });
-    for (const profile of ["beta", "stable", "full"] as const) {
-      expect(parentTimeouts[profile] - childTimeoutFloors[profile], profile).toBeGreaterThanOrEqual(
-        60,
-      );
+    for (const jobName of ["plugin_prerelease", "release_checks", "npm_telegram", "performance"]) {
+      expect(fullReleaseWorkflow.jobs[jobName]["timeout-minutes"], jobName).toBe(15);
     }
-    expect(fullReleaseWorkflow.jobs.release_checks["timeout-minutes"]).toBe(420);
-    expect(fullReleaseWorkflow.jobs.npm_telegram["timeout-minutes"]).toBe(
-      "${{ inputs.release_profile == 'full' && 360 || 120 }}",
-    );
-    expect(fullReleaseWorkflow.jobs.performance["timeout-minutes"]).toBe(360);
     const fullReleaseSource = readFileSync(".github/workflows/full-release-validation.yml", "utf8");
     expect(fullReleaseWorkflow.on.workflow_dispatch.inputs.fail_fast).toEqual({
       description:
-        "Cancel each child workflow after its first failed job; false collects independent failures to completion",
+        "Cancel only an exact active child after its first blocking job; false drains all children to completion",
       required: false,
       default: false,
       type: "boolean",
@@ -953,26 +916,26 @@ describe("scripts/lib/plugin-prerelease-test-plan.mts", () => {
     ] as const) {
       const dispatch: WorkflowStep = fullReleaseWorkflow.jobs[jobName].steps[0];
       expect(dispatch.env?.CHILD_WORKFLOW_KIND).toBe(kind);
-      expect(dispatch.env?.FAIL_FAST).toBe("${{ inputs.fail_fast }}");
-      expect(dispatch.run).toContain('if [[ "$FAIL_FAST" != "true" ]]; then');
-      expect(dispatch.run).toContain("has failed child jobs before the workflow completed");
+      if (jobName === "release_checks") {
+        expect(dispatch.env?.FAIL_FAST).toBe("${{ inputs.fail_fast }}");
+        expect(dispatch.run).toContain('-f fail_fast="$FAIL_FAST"');
+      } else {
+        expect(dispatch.env).not.toHaveProperty("FAIL_FAST");
+      }
     }
     expect(fullReleaseWorkflow.jobs.performance.steps[0].env).not.toHaveProperty("FAIL_FAST");
     expect(fullReleaseSource).toContain('-f fail_fast="$FAIL_FAST"');
-    expect(fullReleaseSource).toContain(
-      "npm-telegram-beta-e2e.yml has failed child jobs before the workflow completed; cancelling the remaining run.",
+    expect(fullReleaseSource).not.toContain(
+      "has failed child jobs before the workflow completed; cancelling the remaining run.",
     );
     expect(fullReleaseSource).not.toContain("trap cancel_child");
     expect(fullReleaseSource).not.toContain("cancel_child_on_failure");
     expect(fullReleaseSource).not.toContain("exit_on_parent_signal");
     expect(fullReleaseSource).not.toContain("disable_child_cleanup");
-    expect(fullReleaseSource).toContain(
-      "Parent cancellation leaves this child running; cancel it explicitly if no longer needed.",
-    );
+    expect(fullReleaseSource).not.toContain("cancel_child");
     expect(fullReleaseSource).toContain(
       'if [[ "$child_head_sha" != "$PARENT_WORKFLOW_SHA" ]]; then',
     );
-    expect(fullReleaseSource).toContain("cancel_child\n              exit 1");
     expect(releaseChecksWorkflow.on.workflow_dispatch.inputs.fail_fast).toEqual({
       description: "Stop the Matrix QA lane after its first failed check or scenario",
       required: false,
@@ -1034,7 +997,7 @@ describe("scripts/lib/plugin-prerelease-test-plan.mts", () => {
       (step: WorkflowStep) => step.name === "Summarize target",
     );
     const releaseChecksDispatch = fullReleaseWorkflow.jobs.release_checks.steps.find(
-      (step: WorkflowStep) => step.name === "Dispatch and monitor release checks",
+      (step: WorkflowStep) => step.name === "Dispatch release checks",
     );
     expect(summarizeTarget?.env?.ALLOW_UNRELEASED_CHANGELOG).toBe(fullReleaseAllowance);
     expect(releaseChecksDispatch?.env?.ALLOW_UNRELEASED_CHANGELOG).toBe(fullReleaseAllowance);
diff --git a/test/scripts/release-ci-summary.test.ts b/test/scripts/release-ci-summary.test.ts
index 170181ea6674..df0fca154477 100644
--- a/test/scripts/release-ci-summary.test.ts
+++ b/test/scripts/release-ci-summary.test.ts
@@ -21,6 +21,7 @@ import {
   selectManifestArtifact,
   selectManifestParentJob,
   selectedChildKeys,
+  tryReadReleaseDecisionArtifact,
   validateEvidenceReuseChain,
   validateManifestArtifactCompatibility,
   validateManifestArtifactIdentity,
@@ -29,6 +30,7 @@ import {
   validateParentRunBinding,
   validatePerformanceArtifactOnlyJobs,
   validateReleaseRunEvidence,
+  validateRequestedEvidenceReuse,
   validateTrustedProducerIdentity,
 } from "../../scripts/release-ci-summary.mjs";
 
@@ -75,7 +77,7 @@ describe("GitHub API commands", () => {
         artifact: fixture.artifact,
         artifactList: { artifacts: [fixture.artifact] },
         child: fixture.childRun,
-        jobLog: `TARGET_SHA: ${targetSha}\nDispatched: https://github.com/openclaw/openclaw/actions/runs/${childRunId}`,
+        jobLog: `TARGET_SHA: ${targetSha}\nDispatched: https://github.com/openclaw/openclaw/actions/runs/${childRunId} (attempt 1)`,
         jobs: { jobs: [fixture.parentJob] },
         lineage: { merge_base_commit: { sha: workflowSha }, status: "ahead" },
         parent: fixture.parentRun,
@@ -314,6 +316,42 @@ describe("runReleaseCiGh", () => {
   });
 });
 
+describe("Release Decision artifact polling", () => {
+  const parent = { attempt: 1, headSha: "a".repeat(40) };
+
+  it("treats transient download transport failures as unavailable this poll", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      expect(
+        tryReadReleaseDecisionArtifact(parent, "123", "openclaw/openclaw", () => {
+          throw Object.assign(new Error("HTTP 503: Server Error"), {
+            stderr: "HTTP 503: Server Error",
+          });
+        }),
+      ).toBeUndefined();
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining("release decision artifact unavailable this poll"),
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("keeps authentication and invocation failures hard", () => {
+    for (const message of [
+      "HTTP 401: Bad credentials",
+      "HTTP 403: secondary rate limit",
+      "unknown flag: --name\nUsage: gh run download",
+    ]) {
+      expect(() =>
+        tryReadReleaseDecisionArtifact(parent, "123", "openclaw/openclaw", () => {
+          throw Object.assign(new Error(message), { stderr: message });
+        }),
+      ).toThrow("release decision artifact read failed");
+    }
+  });
+});
+
 function crc32(input: Buffer): number {
   let crc = 0xffffffff;
   for (const byte of input) {
@@ -609,13 +647,16 @@ function trustedMainPackageFixture({
       expect(jobId).toBe(parentJob.id);
       return [
         `TARGET_SHA: ${targetSha}`,
-        `Dispatched openclaw-release-checks.yml: ${childRun.html_url}`,
+        `Dispatched openclaw-release-checks.yml: ${childRun.html_url} (attempt ${childRun.run_attempt})`,
       ].join("\n");
     },
     getParentJobs(requestedRunId: string) {
       expect(requestedRunId).toBe(runId);
       return [parentJob];
     },
+    getRef(fullRef: string) {
+      return { object: { sha: workflowSha }, ref: fullRef };
+    },
     getRun(requestedRunId: string) {
       if (requestedRunId === runId) {
         return parentRun;
@@ -673,18 +714,43 @@ function createReleaseCiWatchFixture(states: ReleaseCiWatchState[]) {
   writeFileSync(
     ghPath,
     `#!${process.execPath}
-import { appendFileSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 const args = process.argv.slice(2);
 appendFileSync(process.env.RELEASE_CI_WATCH_CALLS, JSON.stringify(args) + "\\n");
 const endpoint = args[1] ?? "";
 const states = ${JSON.stringify(states)};
 let output;
 if (args[0] === "run" && args[1] === "view") {
-  if (args[args.indexOf("--json") + 1] === "status,conclusion,attempt,jobs") {
+  if (args[args.indexOf("--json") + 1] === "status,conclusion,attempt,headSha,jobs") {
     const index = Number(readFileSync(process.env.RELEASE_CI_WATCH_INDEX, "utf8"));
-    output = states[Math.min(index, states.length - 1)];
+    output = { headSha: ${JSON.stringify(fixture.workflowSha)}, ...states[Math.min(index, states.length - 1)] };
     writeFileSync(process.env.RELEASE_CI_WATCH_INDEX, String(index + 1));
   } else output = ${JSON.stringify(parentView)};
+} else if (args[0] === "run" && args[1] === "download") {
+  const dir = args[args.indexOf("--dir") + 1];
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(dir + "/full-release-decision.json", JSON.stringify({
+    version: 2,
+    kind: "openclaw.full-release-decision",
+    mode: "decision",
+    parentRunId: ${JSON.stringify(runId)},
+    parentRunAttempt: 1,
+    sourceParentRunAttempt: 1,
+    workflowRef: "main",
+    workflowSha: ${JSON.stringify(fixture.workflowSha)},
+    targetSha: ${JSON.stringify(fixture.targetSha)},
+    releaseProfile: "stable",
+    rerunGroup: "all",
+    executionPlanSha256: "${"d".repeat(64)}",
+    state: "blocked_diagnostics_running",
+    activeRunIds: ["101"],
+    blockers: [{ child: "normalCi", job: "test", conclusion: "failure", runId: "101", url: "https://example.invalid/job" }],
+    errors: [],
+    cancellation: { requested: false, cancelledRunIds: [] },
+    plan: [{ key: "normalCi", workflow: "ci.yml", displayTitle: "CI", dispatchName: "Dispatch CI", required: true, selected: true, source: "fresh", result: "success", runId: "101", runAttempt: 1, url: "https://example.invalid/run", workflowRef: "main", workflowSha: ${JSON.stringify(fixture.workflowSha)} }],
+    children: {}
+  }));
+  process.exit(0);
 } else if (endpoint === "rate_limit") output = { resources: { core: { limit: 5000, remaining: 4999, reset: 2_000_000_000 } } };
 else if (endpoint === "repos/openclaw/openclaw/actions/runs/${runId}") output = ${JSON.stringify(parent)};
 else if (endpoint.startsWith("repos/openclaw/openclaw/actions/runs/${runId}/artifacts?")) output = { artifacts: [] };
@@ -775,7 +841,7 @@ describe("release CI summary child correlation", () => {
       const watchPolls = calls.filter(
         (args) =>
           args[0] === "run" &&
-          args[args.indexOf("--json") + 1] === "status,conclusion,attempt,jobs",
+          args[args.indexOf("--json") + 1] === "status,conclusion,attempt,headSha,jobs",
       );
       expect(result.status, result.stderr).toBe(0);
       expect(watchPolls).toHaveLength(4);
@@ -813,6 +879,37 @@ describe("release CI summary child correlation", () => {
     }
   });
 
+  it("reports an early release blocker once while the diagnostic drain continues", () => {
+    const fixture = createReleaseCiWatchFixture([
+      {
+        attempt: 1,
+        conclusion: "",
+        jobs: [
+          { conclusion: "failure", name: "Release Decision", status: "completed" },
+          { conclusion: "", name: "Diagnostic Drain", status: "in_progress" },
+        ],
+        status: "in_progress",
+      },
+    ]);
+    try {
+      const result = fixture.run();
+      const calls = fixture.readCalls();
+      expect(result.status).toBe(1);
+      expect(result.stderr).toContain("Full Release Validation state: blocked_diagnostics_running");
+      expect(result.stderr).toContain("Diagnostic Drain is still collecting terminal evidence");
+      expect(
+        calls.filter(
+          (args) =>
+            args[0] === "run" &&
+            args[args.indexOf("--json") + 1] === "status,conclusion,attempt,headSha,jobs",
+        ),
+      ).toHaveLength(1);
+      expect(calls.filter((args) => args[0] === "api" && args[1] === "rate_limit")).toHaveLength(1);
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
   it("selects one immutable manifest artifact bound to the exact parent run", () => {
     const { artifact, runId } = trustedMainPackageFixture();
     const legacyArtifact = {
@@ -878,8 +975,7 @@ describe("release CI summary child correlation", () => {
 
     const source = readFileSync(SCRIPT, "utf8");
     expect(source).toContain("actions/artifacts/${artifactId}/zip");
-    expect(source).not.toContain('"--name",');
-    expect(source).not.toContain("gh run download");
+    expect(source).toContain('"--name",');
     expect(source).toContain(
       "downloadParentManifestEvidence(runId, runAttempt, normalizedRepository, manifestPath)",
     );
@@ -1036,6 +1132,52 @@ describe("release CI summary child correlation", () => {
     });
   });
 
+  it("accepts beta advisory release-check failures through canonical policy", () => {
+    const fixture = trustedMainPackageFixture();
+    fixture.manifest.releaseProfile = "beta";
+    fixture.childRun.conclusion = "failure";
+    const getParentJobs = fixture.client.getParentJobs;
+    fixture.client.getParentJobs = (requestedRunId: string) =>
+      requestedRunId === String(fixture.childRun.id)
+        ? [
+            {
+              completed_at: "2026-07-10T01:10:00Z",
+              conclusion: "failure",
+              id: 86293408711,
+              name: "Run QA Lab parity lane (core)",
+              run_attempt: 1,
+              started_at: "2026-07-10T01:00:00Z",
+              status: "completed",
+              steps: [],
+            },
+            {
+              completed_at: "2026-07-10T01:10:00Z",
+              conclusion: "success",
+              id: 86293408712,
+              name: "Verify release checks",
+              run_attempt: 1,
+              started_at: "2026-07-10T01:00:00Z",
+              status: "completed",
+              steps: [],
+            },
+          ]
+        : getParentJobs(requestedRunId);
+
+    const evidence = validateReleaseRunEvidence(
+      {
+        repository: "openclaw/openclaw",
+        runId: fixture.runId,
+        verifierSourceContent: readFileSync(SCRIPT),
+        verifierSourceSha: "c".repeat(40),
+      },
+      fixture.client,
+    );
+    expect(evidence.conclusions).toMatchObject({
+      allRequiredSucceeded: true,
+      children: { releaseChecks: "failure" },
+    });
+  });
+
   it("accepts a trusted-main producer when the candidate is the same main commit", () => {
     const sharedSha = "a".repeat(40);
     const fixture = trustedMainPackageFixture({
@@ -1267,6 +1409,10 @@ describe("release CI summary child correlation", () => {
       workflowSha: olderWorkflowSha,
     });
     olderFixture.manifest.targetRef = olderFixture.targetSha;
+    olderFixture.client.getRef = (fullRef: string) => ({
+      object: { sha: trustedWorkflowSha },
+      ref: fullRef,
+    });
     expect(() =>
       validateReleaseRunEvidence(
         {
@@ -1304,6 +1450,44 @@ describe("release CI summary child correlation", () => {
     ).toThrow("canonical release-ci branch");
   });
 
+  it("rejects a protected tooling tag that moved or disappeared after sealing", () => {
+    const workflowSha = "7".repeat(40);
+    const workflowRef = `release-ci/${workflowSha.slice(0, 12)}-1783705000000`;
+    const trustedWorkflowRef = `release-publish/${workflowSha.slice(0, 12)}-123`;
+    const fixture = trustedMainPackageFixture({
+      manifestVersion: 3,
+      targetSha: "8".repeat(40),
+      workflowFullRef: `refs/heads/${workflowRef}`,
+      workflowRef,
+      workflowSha,
+    });
+    fixture.manifest.targetRef = fixture.targetSha;
+    const options = {
+      repository: "openclaw/openclaw",
+      runId: fixture.runId,
+      trustedWorkflowFullRef: `refs/tags/${trustedWorkflowRef}`,
+      trustedWorkflowRef,
+      trustedWorkflowSha: workflowSha,
+      verifierSourceContent: readFileSync(SCRIPT),
+      verifierSourceSha: "c".repeat(40),
+    };
+
+    fixture.client.getRef = (fullRef: string) => ({
+      object: { sha: "6".repeat(40) },
+      ref: fullRef,
+    });
+    expect(() => validateReleaseRunEvidence(options, fixture.client)).toThrow(
+      "protected tooling tag moved",
+    );
+
+    fixture.client.getRef = () => {
+      throw new Error("HTTP 404");
+    };
+    expect(() => validateReleaseRunEvidence(options, fixture.client)).toThrow(
+      "protected tooling tag is unavailable",
+    );
+  });
+
   it.each(["main", "refs/heads/main"])(
     "accepts a REST workflow path qualified with %s",
     (qualifiedRef) => {
@@ -2067,7 +2251,7 @@ describe("release CI summary child correlation", () => {
     ];
     const parentLog = [
       `TARGET_SHA: ${parentManifest.targetSha}`,
-      "Dispatched ci.yml: https://github.com/openclaw/openclaw/actions/runs/101",
+      "Dispatched ci.yml: https://github.com/openclaw/openclaw/actions/runs/101 (attempt 1)",
     ].join("\n");
     const run = {
       actor: { login: "github-actions[bot]" },
@@ -2178,7 +2362,7 @@ describe("release CI summary child correlation", () => {
       const parentLog = [
         `TARGET_SHA: ${parentManifest.targetSha}`,
         ...(child.manifestKey === "productPerformance" ? ["-f publish_reports=false"] : []),
-        `Dispatched ${child.workflow}: https://github.com/openclaw/openclaw/actions/runs/${runId}`,
+        `Dispatched ${child.workflow}: https://github.com/openclaw/openclaw/actions/runs/${runId} (attempt ${run.run_attempt})`,
       ].join("\n");
       expect(resolveManifestChildOriginAttempt(run, child, parentManifest, parentJobs)).toBe(
         originAttempt,
@@ -2186,6 +2370,16 @@ describe("release CI summary child correlation", () => {
       expect(
         validateManifestChildRun(run, child, String(runId), parentManifest, parentJobs, parentLog),
       ).toBe(run);
+      expect(
+        validateManifestChildRun(
+          run,
+          child,
+          String(runId),
+          parentManifest,
+          parentJobs,
+          parentLog.replace(` (attempt ${run.run_attempt})`, ""),
+        ),
+      ).toBe(run);
       if (child.manifestKey === "productPerformance") {
         expect(() =>
           validateManifestChildRun(
@@ -2221,7 +2415,7 @@ describe("release CI summary child correlation", () => {
     ];
     const ciLog = [
       `TARGET_SHA: ${parentManifest.targetSha}`,
-      "Dispatched ci.yml: https://github.com/openclaw/openclaw/actions/runs/101",
+      "Dispatched ci.yml: https://github.com/openclaw/openclaw/actions/runs/101 (attempt 1)",
     ].join("\n");
     expect(() =>
       validateManifestChildRun(wrongParent, ci, "101", parentManifest, ciJobs, ciLog),
@@ -2244,6 +2438,115 @@ describe("release CI summary child correlation", () => {
     ).toBeUndefined();
   });
 
+  it("keeps requested changelog reuse target and evidence SHAs separate", () => {
+    const evidenceSha = "a".repeat(40);
+    const targetSha = "b".repeat(40);
+    expect(() =>
+      validateRequestedEvidenceReuse(
+        {
+          evidenceReuse: {
+            changedPaths: ["CHANGELOG.md"],
+            evidenceSha,
+            policy: "changelog-only-release-v1",
+            runId: "101",
+            selectedRunId: "101",
+          },
+          runId: "101",
+          targetSha,
+        },
+        { runId: "101", targetSha: evidenceSha },
+        { runId: "101", targetSha: evidenceSha },
+        {
+          expectedChangedPaths: ["CHANGELOG.md"],
+          expectedEvidencePolicy: "changelog-only-release-v1",
+          expectedEvidenceSha: evidenceSha,
+          expectedRootRunId: "101",
+          expectedSelectedRunId: "101",
+          expectedTargetSha: targetSha,
+        },
+      ),
+    ).not.toThrow();
+    expect(() =>
+      validateRequestedEvidenceReuse(
+        {
+          evidenceReuse: {
+            changedPaths: ["CHANGELOG.md"],
+            evidenceSha,
+            policy: "changelog-only-release-v1",
+            runId: "101",
+            selectedRunId: "101",
+          },
+          runId: "101",
+          targetSha,
+        },
+        { runId: "101", targetSha },
+        { runId: "101", targetSha },
+        {
+          expectedChangedPaths: ["CHANGELOG.md"],
+          expectedEvidencePolicy: "changelog-only-release-v1",
+          expectedEvidenceSha: evidenceSha,
+          expectedRootRunId: "101",
+          expectedSelectedRunId: "101",
+          expectedTargetSha: targetSha,
+        },
+      ),
+    ).toThrow("no longer matches");
+  });
+
+  it.each([
+    {
+      changedPaths: [],
+      policy: "exact-target-full-validation-v1",
+      targetSha: "a".repeat(40),
+    },
+    {
+      changedPaths: ["CHANGELOG.md"],
+      policy: "changelog-only-release-v1",
+      targetSha: "b".repeat(40),
+    },
+  ])("validates the complete prospective $policy selection tuple", (selection) => {
+    const root = validateParentManifest(rawManifest({}), {
+      runAttempt: 2,
+      runId: "29090000000",
+    });
+    expect(() =>
+      validateRequestedEvidenceReuse(
+        root,
+        root,
+        root,
+        {
+          expectedChangedPaths: selection.changedPaths,
+          expectedEvidencePolicy: selection.policy,
+          expectedEvidenceSha: root.targetSha,
+          expectedRootRunId: root.runId,
+          expectedSelectedRunId: root.runId,
+          expectedTargetSha: selection.targetSha,
+        },
+        (base: string) => ({
+          files: [{ filename: "CHANGELOG.md", status: "modified" }],
+          merge_base_commit: { sha: base },
+          status: "ahead",
+        }),
+      ),
+    ).not.toThrow();
+    expect(() =>
+      validateRequestedEvidenceReuse(
+        root,
+        root,
+        root,
+        {
+          expectedChangedPaths: selection.changedPaths,
+          expectedEvidencePolicy: selection.policy,
+          expectedEvidenceSha: root.targetSha,
+          expectedRootRunId: root.runId,
+          expectedSelectedRunId: "29090000001",
+          expectedTargetSha: selection.targetSha,
+        },
+        () => ({ status: "identical" }),
+      ),
+    ).toThrow("no longer matches");
+  });
+
   it("rejects carried parent jobs whose selected-attempt execution fingerprint changed", () => {
     const child = expectedChildDispatches("28717729503", 2, "main").find(
       (entry) => entry.manifestKey === "pluginPrerelease",
diff --git a/test/scripts/release-no-push-workflow.test.ts b/test/scripts/release-no-push-workflow.test.ts
index 73b2c6a2acc5..89293515bf18 100644
--- a/test/scripts/release-no-push-workflow.test.ts
+++ b/test/scripts/release-no-push-workflow.test.ts
@@ -300,7 +300,7 @@ describe("release validation no-push transport", () => {
     const release = readWorkflow(RELEASE_CHECKS);
     const umbrellaGroups = full.on?.workflow_dispatch?.inputs?.rerun_group?.options ?? [];
     const releaseGroups = release.on?.workflow_dispatch?.inputs?.rerun_group?.options ?? [];
-    const dispatch = step(job(full, "release_checks"), "Dispatch and monitor release checks");
+    const dispatch = step(job(full, "release_checks"), "Dispatch release checks");
     const capture = step(job(release, "resolve_target"), "Capture selected inputs");
     const parentFilters = step(job(full, "resolve_target"), "Validate suite filters");
 
@@ -337,12 +337,6 @@ describe("release validation no-push transport", () => {
     expect(candidate.if).toContain(
       "(inputs.rerun_group == 'live-e2e' && needs.resolve_target.outputs.live_suite_filter == '')",
     );
-    const verify = step(job(full, "summary"), "Verify child workflow results");
-    expect(verify.env?.LIVE_SUITE_FILTER).toBe(
-      "${{ needs.resolve_target.outputs.live_suite_filter }}",
-    );
-    expect(verify.run).toContain('[[ -n "${LIVE_SUITE_FILTER// }" ]] || candidate_required=1');
-
     expect(capture.run).toContain(
       "release_check_groups=(install-smoke cross-os package qa-parity)",
     );
@@ -768,14 +762,14 @@ describe("release validation no-push transport", () => {
     expect(releaseHelper.with?.["persist-credentials"]).toBe(false);
   });
 
-  it("records adopted children before monitoring and cancels only a mismatched workflow SHA", () => {
+  it("records exact adopted child identity without monitoring or cancellation", () => {
     const full = readWorkflow(FULL_RELEASE);
     for (const [jobName, stepName] of [
-      ["normal_ci", "Dispatch and monitor CI"],
-      ["plugin_prerelease", "Dispatch and monitor plugin prerelease"],
-      ["release_checks", "Dispatch and monitor release checks"],
-      ["npm_telegram", "Dispatch and monitor npm Telegram E2E"],
-      ["performance", "Dispatch and monitor OpenClaw Performance"],
+      ["normal_ci", "Dispatch CI"],
+      ["plugin_prerelease", "Dispatch plugin prerelease"],
+      ["release_checks", "Dispatch release checks"],
+      ["npm_telegram", "Dispatch npm Telegram E2E"],
+      ["performance", "Dispatch OpenClaw Performance"],
     ] as const) {
       const dispatch = step(job(full, jobName), stepName);
       const dispatchRun = dispatch.run ?? "";
@@ -789,42 +783,25 @@ describe("release validation no-push transport", () => {
       expect(dispatchRun, jobName).not.toContain("cancel_child_on_failure");
       expect(dispatchRun, jobName).not.toContain("exit_on_parent_signal");
       expect(dispatchRun, jobName).not.toContain("disable_child_cleanup");
+      expect(dispatchRun, jobName).not.toContain("poll_count=0");
+      expect(dispatchRun, jobName).not.toContain("cancel_child");
       expect(
         dispatchRun.indexOf('run_json="$(validate_child_run "$run_id")"'),
         jobName,
       ).toBeLessThan(dispatchRun.indexOf('echo "run_id=${run_id}" >> "$GITHUB_OUTPUT"'));
-      expect(
-        dispatchRun.indexOf('echo "run_id=${run_id}" >> "$GITHUB_OUTPUT"'),
-        jobName,
-      ).toBeLessThan(dispatchRun.indexOf("poll_count=0"));
       expect(
         dispatchRun.indexOf('run_json="$(validate_child_run "$run_id")"'),
         jobName,
       ).toBeLessThan(dispatchRun.indexOf('if [[ "$child_head_sha" != "$PARENT_WORKFLOW_SHA" ]]'));
-      const shaMismatch = dispatchRun.slice(
-        dispatchRun.indexOf('if [[ "$child_head_sha" != "$PARENT_WORKFLOW_SHA" ]]'),
-        dispatchRun.indexOf("fail_fast_failed_jobs()"),
-      );
-      expect(shaMismatch, jobName).toContain("cancel_child");
-      expect(shaMismatch, jobName).not.toContain("trap");
     }
-
-    const verify = step(job(full, "summary"), "Verify child workflow results");
-    expect(verify.env?.PARENT_WORKFLOW_SHA).toBe("${{ github.sha }}");
-    expect(verify.run).toContain('"$head_sha" != "$PARENT_WORKFLOW_SHA"');
-    expect(verify.run).not.toContain('"$head_sha" != "$TARGET_SHA"');
   });
 
   it("keeps the Release SHA wrapper as the durable evidence identity", () => {
     const full = readWorkflow(FULL_RELEASE);
-    const verify = step(job(full, "summary"), "Verify child workflow results");
+    const verify = step(job(full, "summary"), "Verify exact release state artifacts");
     const dispatch = step(job(full, "summary"), "Request release evidence update");
 
-    expect(verify.run).toContain(
-      'echo "Dispatched ${workflow}: https://github.com/${GITHUB_REPOSITORY}/actions/runs/${run_id}"',
-    );
-    expect(verify.run).toContain('"ci.yml"');
-    expect(verify.run).toContain('"openclaw-release-checks.yml"');
+    expect(verify.run).toBe("node scripts/full-release-validation-state.mjs verify");
     expect(dispatch.run).not.toContain('GITHUB_RUN_ID_VALUE="$EVIDENCE_ROOT_RUN_ID"');
     expect(dispatch.run).toContain("reused green product evidence from chain-root run");
     expect(dispatch.run).toContain("--connect-timeout 10");
@@ -849,9 +826,9 @@ describe("release validation no-push transport", () => {
     const packageAcceptance = readWorkflow(PACKAGE_ACCEPTANCE);
     const pluginPrerelease = readWorkflow(PLUGIN_PRERELEASE);
 
-    expect(fullText).toContain("dispatch_and_wait plugin-prerelease.yml");
-    expect(fullText).toContain("dispatch_and_wait openclaw-release-checks.yml");
-    expect(fullText).toContain("dispatch_and_wait openclaw-performance.yml");
+    expect(fullText).toContain("dispatch_child plugin-prerelease.yml");
+    expect(fullText).toContain("dispatch_child openclaw-release-checks.yml");
+    expect(fullText).toContain("dispatch_child openclaw-performance.yml");
     expect(fullText).toContain('gh workflow run "$workflow" --ref "$CHILD_WORKFLOW_REF" "$@"');
 
     const preparePackage = job(release, "prepare_release_package");

From 975027aee9904e7554853d3ae5153ee52a2e09ca Mon Sep 17 00:00:00 2001
From: ClawSweeper <steipete+clawsweeper@gmail.com>
Date: Fri, 21 Aug 2026 09:18:52 -0700
Subject: [PATCH 027/124] fix(ui): remove redundant mobile header alerts
 (#127235)

Co-authored-by: RoboClaw <309084314+roboclaw-bot@users.noreply.github.com>
Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>
---
 ui/src/app/app-host-native-shell.test.ts      |  53 ++++++---
 ui/src/app/app-shell-view.ts                  |   1 +
 ui/src/app/navigation-surface.browser.test.ts |   1 +
 ui/src/app/navigation-surface.ts              |   6 +-
 ui/src/e2e/sidebar-customization.e2e.test.ts  | 101 ++++++++++++++++++
 5 files changed, 149 insertions(+), 13 deletions(-)

diff --git a/ui/src/app/app-host-native-shell.test.ts b/ui/src/app/app-host-native-shell.test.ts
index 9bba7eeef9ba..31bdb0a6b1a0 100644
--- a/ui/src/app/app-host-native-shell.test.ts
+++ b/ui/src/app/app-host-native-shell.test.ts
@@ -386,6 +386,7 @@ describe("OpenClaw shell update affordance", () => {
     const container = document.createElement("div");
     document.body.append(container);
     const shared = {
+      mobileNavLayout: false,
       onboarding: false,
       updateAvailable: {
         currentVersion: "2026.7.1",
@@ -454,28 +455,56 @@ describe("OpenClaw shell update affordance", () => {
     container.remove();
   });
 
-  it("treats a closed mobile drawer as hidden navigation", () => {
-    expect(
-      navigationSurfaceIsHidden({
+  it("keeps attention in the closed mobile drawer while preserving stale-client refresh", async () => {
+    const container = document.createElement("div");
+    document.body.append(container);
+    try {
+      const navigationSurfaceHidden = navigationSurfaceIsHidden({
         onboarding: false,
         navCollapsed: false,
         navDrawerOpen: false,
         mobileNavLayout: true,
-      }),
-    ).toBe(true);
-    expect(
-      navigationSurfaceIsHidden({
-        onboarding: false,
-        navCollapsed: false,
-        navDrawerOpen: true,
+      });
+      expect(navigationSurfaceHidden).toBe(true);
+      const shared = {
+        navigationSurfaceHidden,
         mobileNavLayout: true,
-      }),
-    ).toBe(false);
+        onboarding: false,
+        updateAvailable: {
+          currentVersion: "2026.7.1",
+          latestVersion: "2026.7.2",
+          channel: "stable" as const,
+        },
+        updateBusy: false,
+        canUpdate: true,
+        onUpdate: vi.fn(),
+        refreshRequired: false,
+        onRefresh: vi.fn(),
+      };
+
+      render(renderFloatingUpdateCard(shared), container);
+      expect(
+        container.querySelector("openclaw-sidebar-attention.sidebar-attention--floating"),
+      ).toBeNull();
+
+      render(
+        renderFloatingUpdateCard({ ...shared, updateAvailable: null, refreshRequired: true }),
+        container,
+      );
+      const refreshCard = container.querySelector<
+        HTMLElement & { updateComplete: Promise<boolean> }
+      >("openclaw-sidebar-update-card");
+      await refreshCard?.updateComplete;
+      expect(refreshCard?.querySelector(".sidebar-update-card")).not.toBeNull();
+    } finally {
+      container.remove();
+    }
   });
 
   it("keeps the stale-client refresh visible during onboarding", () => {
     const container = document.createElement("div");
     const shared = {
+      mobileNavLayout: false,
       onboarding: true,
       updateAvailable: null,
       updateBusy: false,
diff --git a/ui/src/app/app-shell-view.ts b/ui/src/app/app-shell-view.ts
index b5098bbaa408..33ca29f8e93b 100644
--- a/ui/src/app/app-shell-view.ts
+++ b/ui/src/app/app-shell-view.ts
@@ -620,6 +620,7 @@ export function renderApplicationShell(host: ShellViewHost) {
         ${renderScopeUpgradeBanner(host, gatewaySnapshot, mergedChatChrome)}
         ${renderFloatingUpdateCard({
           navigationSurfaceHidden,
+          mobileNavLayout,
           onboarding,
           compact: mergedChatChrome,
           updateAvailable: overlaySnapshot.updateAvailable,
diff --git a/ui/src/app/navigation-surface.browser.test.ts b/ui/src/app/navigation-surface.browser.test.ts
index 1f5637c75727..904c26156a49 100644
--- a/ui/src/app/navigation-surface.browser.test.ts
+++ b/ui/src/app/navigation-surface.browser.test.ts
@@ -50,6 +50,7 @@ describe.skipIf(!hasBrowserLayout)("navigation surface browser layout", () => {
           <main class="content">
             ${renderFloatingUpdateCard({
               navigationSurfaceHidden: true,
+              mobileNavLayout: false,
               onboarding: false,
               updateAvailable: null,
               updateBusy: false,
diff --git a/ui/src/app/navigation-surface.ts b/ui/src/app/navigation-surface.ts
index 7af2a779f13e..7b6ab8f3e299 100644
--- a/ui/src/app/navigation-surface.ts
+++ b/ui/src/app/navigation-surface.ts
@@ -16,6 +16,7 @@ export function navigationSurfaceIsHidden(params: {
 
 export function renderFloatingUpdateCard(params: {
   navigationSurfaceHidden: boolean;
+  mobileNavLayout: boolean;
   onboarding: boolean;
   compact?: boolean;
   updateAvailable: ApplicationContext["overlays"]["snapshot"]["updateAvailable"];
@@ -36,7 +37,10 @@ export function renderFloatingUpdateCard(params: {
 }) {
   // A stale client must always have a visible refresh action, including during
   // onboarding, even though update-available actions stay hidden there.
-  const showAttention = params.navigationSurfaceHidden && !params.onboarding && !params.compact;
+  // Mobile keeps attention in its drawer; desktop collapse has no drawer, so
+  // it still needs the floating copy while navigation is hidden.
+  const desktopNavigationHidden = params.navigationSurfaceHidden && !params.mobileNavLayout;
+  const showAttention = desktopNavigationHidden && !params.onboarding && !params.compact;
   const showUpdateCard =
     !params.compact &&
     (params.onboarding ? params.refreshRequired : params.navigationSurfaceHidden);
diff --git a/ui/src/e2e/sidebar-customization.e2e.test.ts b/ui/src/e2e/sidebar-customization.e2e.test.ts
index 8a9f56af8876..01cdc0c7e902 100644
--- a/ui/src/e2e/sidebar-customization.e2e.test.ts
+++ b/ui/src/e2e/sidebar-customization.e2e.test.ts
@@ -691,6 +691,107 @@ suite.define(() => {
     );
   });
 
+  it("keeps mobile attention in the drawer while desktop remains unchanged", async () => {
+    await suite.withPage(
+      {
+        locale: "en-US",
+        serviceWorkers: "block",
+        viewport: { height: 900, width: 1440 },
+      },
+      async ({ page }) => {
+        const gateway = await installMockGateway(page, {
+          methodResponses: {
+            "cron.list": {
+              jobs: [
+                {
+                  id: "release-digest",
+                  name: "Release digest",
+                  enabled: true,
+                  createdAtMs: 0,
+                  updatedAtMs: 0,
+                  schedule: { kind: "every", everyMs: 60_000 },
+                  sessionTarget: "isolated",
+                  wakeMode: "now",
+                  payload: { kind: "agentTurn", message: "test" },
+                  state: {
+                    lastRunStatus: "error",
+                    lastError: "Provider request failed",
+                  },
+                },
+              ],
+              snapshotRevision: "sidebar-mobile-attention",
+              total: 1,
+              offset: 0,
+              limit: 50,
+              hasMore: false,
+              nextOffset: null,
+            },
+            "models.authStatus": { providers: [], ts: 1 },
+          },
+        });
+
+        await page.goto(`${suite.server.baseUrl}new`);
+        await gateway.waitForRequest("cron.list");
+        await gateway.emitGatewayEvent("update.available", {
+          schedule: {
+            autoEnabled: false,
+            channel: "dev",
+            install: { kind: "git", git: { status: "behind", commitsBehind: 246 } },
+            target: {
+              kind: "git",
+              commitsBehind: 246,
+              upstreamRef: "origin/main",
+              upstreamSha: "9f3c21a0000000000000000000000000000000aa",
+            },
+          },
+          updateAvailable: {
+            channel: "dev",
+            commitsBehind: 246,
+            currentSha: "1111111111111111111111111111111111111111",
+            currentVersion: "2026.8.1",
+            latestVersion: "2026.8.1",
+            upstreamRef: "origin/main",
+            upstreamSha: "9f3c21a0000000000000000000000000000000aa",
+          },
+        });
+
+        const sidebar = page.locator("openclaw-app-sidebar");
+        const sidebarUpdate = sidebar.locator('[data-attention-kind="updateAvailable"]');
+        const sidebarAutomation = sidebar.locator('[data-attention-kind="cronFailed"]');
+        await expect.poll(() => sidebarUpdate.count()).toBe(1);
+        await expect.poll(() => sidebarAutomation.count()).toBe(1);
+        await captureUiProof(page, "08-desktop-attention-unchanged.png");
+
+        await page.setViewportSize({ height: 852, width: 393 });
+        await expect
+          .poll(() => page.locator(".shell").getAttribute("class"))
+          .toContain("shell--mobile-nav");
+        await page.evaluate(
+          () =>
+            new Promise<void>((resolve) => {
+              requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+            }),
+        );
+        const floatingKinds = await page
+          .locator(".sidebar-attention--floating [data-attention-kind]")
+          .evaluateAll((elements) =>
+            elements.map((element) => element.getAttribute("data-attention-kind")),
+          );
+        await captureUiProof(page, "09-mobile-attention-closed.png");
+
+        await visibleDrawerButton(page).click();
+        await expect
+          .poll(() => page.locator(".shell").getAttribute("class"))
+          .toContain("shell--nav-drawer-open");
+        await expect.poll(() => sidebarUpdate.isVisible()).toBe(true);
+        await expect.poll(() => sidebarAutomation.isVisible()).toBe(true);
+        await captureUiProof(page, "10-mobile-attention-drawer.png");
+
+        expect(floatingKinds).toEqual([]);
+      },
+    );
+  });
+
   it("passes failed run outcomes through the desktop and drawer sidebar", async () => {
     await suite.withPage(
       {

From d993742d2c88134e15f6b629f5d9517aee4fd10b Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Fri, 21 Aug 2026 09:20:56 -0700
Subject: [PATCH 028/124] test(gateway): repair release-validation fixtures
 (#127263)

* test(onboard): preserve prompt defaults in inference E2E

* test(clawhub): identify skill fixture source
---
 scripts/e2e/lib/clawhub-fixture-server.cjs        | 1 +
 src/commands/onboard-guided.inference.e2e.test.ts | 7 ++++++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/scripts/e2e/lib/clawhub-fixture-server.cjs b/scripts/e2e/lib/clawhub-fixture-server.cjs
index c6072248c2ae..1633d85cbe78 100644
--- a/scripts/e2e/lib/clawhub-fixture-server.cjs
+++ b/scripts/e2e/lib/clawhub-fixture-server.cjs
@@ -699,6 +699,7 @@ profiles["catalog-search"] = {
     skills: [
       {
         score: 99,
+        source: "clawhub",
         slug: "calendar-skill",
         ownerHandle: "acme",
         displayName: "Calendar Skill",
diff --git a/src/commands/onboard-guided.inference.e2e.test.ts b/src/commands/onboard-guided.inference.e2e.test.ts
index 528d1b07d1de..6e5af419e92e 100644
--- a/src/commands/onboard-guided.inference.e2e.test.ts
+++ b/src/commands/onboard-guided.inference.e2e.test.ts
@@ -97,7 +97,12 @@ describe("guided onboarding inference composition", () => {
         })}\n`,
       );
 
-      const prompter = createWizardPrompter(undefined, { selectValues: ["full", "use"] });
+      const prompter = createWizardPrompter(
+        {
+          text: vi.fn(async ({ initialValue }) => initialValue ?? ""),
+        },
+        { selectValues: ["full", "use"] },
+      );
       const runSetupMemoryImportStep = vi.fn(async () => ({
         status: "skipped" as const,
         providers: [],

From 7600b2a36a9f51463e2944e0849309b28d8dba4e Mon Sep 17 00:00:00 2001
From: Dallin Romney <dallinromney@gmail.com>
Date: Fri, 21 Aug 2026 09:27:28 -0700
Subject: [PATCH 029/124] test(release): honor Codex ultra request mapping
 (#127058)

---
 src/gateway/gateway-codex-harness.live.test.ts | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/gateway/gateway-codex-harness.live.test.ts b/src/gateway/gateway-codex-harness.live.test.ts
index 80ebb9fa880b..b88f6f29acc4 100644
--- a/src/gateway/gateway-codex-harness.live.test.ts
+++ b/src/gateway/gateway-codex-harness.live.test.ts
@@ -276,11 +276,11 @@ function resolveCodexHarnessThinkingLevel(raw: string | undefined): CodexHarness
   return normalized as CodexHarnessThinkingLevel;
 }
 
-function resolveCodexHarnessExpectedEffort(modelId: string): string | null {
+function resolveCodexHarnessExpectedRequestEffort(modelId: string): string | null {
   const configured = process.env.OPENCLAW_LIVE_CODEX_HARNESS_EXPECTED_EFFORT;
   if (configured?.trim()) {
     const expected = resolveCodexHarnessThinkingLevel(configured);
-    return expected === "off" ? null : expected;
+    return expected === "off" ? null : expected === "ultra" ? "max" : expected;
   }
   const supported = CODEX_HARNESS_SUPPORTED_EFFORTS.get(modelId);
   if (!supported) {
@@ -289,14 +289,14 @@ function resolveCodexHarnessExpectedEffort(modelId: string): string | null {
   if (CODEX_HARNESS_THINKING === "off") {
     return null;
   }
-  // Independent oracle for the pinned Codex model catalog. Lower requested
-  // levels choose the nearest advertised effort; Ultra remains explicit.
+  // Codex preserves Ultra in config but intentionally sends Max to the model.
+  // Compare the request-facing lifecycle event to that wire contract.
   const candidates =
     CODEX_HARNESS_THINKING === "ultra"
       ? supported
       : supported.filter((effort) => effort !== "ultra");
   const requestedRank = CODEX_HARNESS_REASONING_EFFORTS.indexOf(CODEX_HARNESS_THINKING);
-  return (
+  const configuredEffort =
     candidates.find(
       (effort) =>
         CODEX_HARNESS_REASONING_EFFORTS.indexOf(
@@ -304,8 +304,8 @@ function resolveCodexHarnessExpectedEffort(modelId: string): string | null {
         ) >= requestedRank,
     ) ??
     candidates.at(-1) ??
-    null
-  );
+    null;
+  return configuredEffort === "ultra" ? "max" : configuredEffort;
 }
 
 function logCodexLiveStep(step: string, details?: Record<string, unknown>): void {
@@ -846,7 +846,7 @@ function recordCodexAttemptIdentity(params: {
   expect(turnStarting?.data).toMatchObject({ model: expectedModel });
   const actualEffort = turnStarting?.data?.effort;
   const actualCollaborationEffort = turnStarting?.data?.collaborationEffort;
-  const expectedEffort = resolveCodexHarnessExpectedEffort(expectedModel);
+  const expectedEffort = resolveCodexHarnessExpectedRequestEffort(expectedModel);
   expect(actualEffort ?? null).toBe(expectedEffort);
   expect(actualCollaborationEffort ?? null).toBe(actualEffort ?? null);
   if (CODEX_HARNESS_FULL_CONTEXT) {

From c4d07b398b87a85562c82d0dad6c238d0d9d286e Mon Sep 17 00:00:00 2001
From: Dallin Romney <dallinromney@gmail.com>
Date: Fri, 21 Aug 2026 09:28:36 -0700
Subject: [PATCH 030/124] fix(release): allow unreleased changelog in SHA
 preflight (#127019)

---
 .github/workflows/openclaw-npm-release.yml                 | 5 +++++
 test/scripts/openclaw-npm-extended-stable-workflow.test.ts | 3 +++
 2 files changed, 8 insertions(+)

diff --git a/.github/workflows/openclaw-npm-release.yml b/.github/workflows/openclaw-npm-release.yml
index 320421f2c168..000871a0ee70 100644
--- a/.github/workflows/openclaw-npm-release.yml
+++ b/.github/workflows/openclaw-npm-release.yml
@@ -516,6 +516,11 @@ jobs:
             fi
           fi
           PACK_OUTPUT="$RUNNER_TEMP/npm-pack-output.txt"
+          if [[ "${RELEASE_REF}" =~ ^[0-9a-fA-F]{40}$ ]]; then
+            # Validation-only SHA runs package unreleased main; real release tags
+            # still require their exact versioned changelog section.
+            export OPENCLAW_PREPACK_ALLOW_UNRELEASED_CHANGELOG=1
+          fi
           pnpm pack --json 2>&1 | tee "$PACK_OUTPUT"
           PACK_NAME="$(node - "$PACK_OUTPUT" <<'NODE'
           const fs = require("node:fs");
diff --git a/test/scripts/openclaw-npm-extended-stable-workflow.test.ts b/test/scripts/openclaw-npm-extended-stable-workflow.test.ts
index 2ca2caf69277..54a6de70cc42 100644
--- a/test/scripts/openclaw-npm-extended-stable-workflow.test.ts
+++ b/test/scripts/openclaw-npm-extended-stable-workflow.test.ts
@@ -273,8 +273,11 @@ describe("minimal npm extended-stable workflow", () => {
     const parsed = workflow();
     const preflight = parsed.jobs?.preflight_openclaw_npm;
     const metadata = step(preflight, "Validate release metadata");
+    const pack = step(preflight, "Pack prepared npm tarball");
     expect(metadata.run).toContain('RELEASE_BRANCH_REF="${RELEASE_SHA}"');
     expect(metadata.run).not.toContain("Validation-only SHA mode only supports");
+    expect(pack.run).toContain('if [[ "${RELEASE_REF}" =~ ^[0-9a-fA-F]{40}$ ]]');
+    expect(pack.run).toContain("export OPENCLAW_PREPACK_ALLOW_UNRELEASED_CHANGELOG=1");
 
     const plugins = step(preflight, "Exercise all extended-stable plugin npm packages");
     expect(step(preflight, "Verify release contents").env).toMatchObject({

From 830196c62855bf1d7284b54e233375e10c5e447c Mon Sep 17 00:00:00 2001
From: Eden <146086744+edenfunf@users.noreply.github.com>
Date: Sat, 22 Aug 2026 00:31:50 +0800
Subject: [PATCH 031/124] fix(scripts): keep Windows lint runs from failing
 before any file is checked (#126274)

* fix(scripts): keep Windows lint runs from failing before any file is checked

`pnpm lint:extensions` aborts on Windows whenever the plugin SDK boundary
cache is cold: the boundary prep spawns `node_modules/.bin/tsgo` directly,
and Windows cannot execute the extensionless pnpm shim, so the run dies with
ENOENT before oxlint checks a single file. The stylelint runner reached by
`check-changed` fails the same way for the same reason.

Both now build their child process with `createManagedCommandInvocation`,
the launcher every other repo tool runner already uses, which routes the shim
through cmd.exe on Windows and returns the command unchanged everywhere else.

Off Windows the spawned command, arguments, and options are byte-identical to
before, so only the broken platform changes behavior.

* fix(scripts): stop the lint pipeline from spawning a tool shim directly

`pnpm lint` reaches stylelint through the same raw shim spawn that broke the
boundary prep, so the pipeline dies on Windows after oxlint succeeds. Route it
through the managed launcher like every other tool runner.

The remaining hazard is structural: the resolver hands out a path that only
some callers know to normalize, and the three sites that forgot were spread
across two spawn shapes. Add a static guard so a shim can only flow into a
launcher that understands the platform, and so the next occurrence fails on
Linux CI instead of on a contributor's Windows machine.

* test(scripts): trim Windows shim regression coverage

Punchcard-Session: cobalt-orchard-willow-2q

---------

Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
---
 ...e-extension-package-boundary-artifacts.mts | 21 +++++++++++++------
 scripts/run-lint.mts                          |  9 +++++---
 scripts/run-stylelint.mts                     | 17 ++++++++++-----
 test/scripts/managed-child-process.test.ts    | 11 +++++++---
 4 files changed, 41 insertions(+), 17 deletions(-)

diff --git a/scripts/prepare-extension-package-boundary-artifacts.mts b/scripts/prepare-extension-package-boundary-artifacts.mts
index cc0c66e1f1a0..6fd364d385ea 100644
--- a/scripts/prepare-extension-package-boundary-artifacts.mts
+++ b/scripts/prepare-extension-package-boundary-artifacts.mts
@@ -22,7 +22,10 @@ import {
   isLocalCheckEnabled,
   resolveRepoToolBinPath,
 } from "./lib/local-check-runtime.mts";
-import { terminateManagedChild } from "./lib/managed-child-process.mts";
+import {
+  createManagedCommandInvocation,
+  terminateManagedChild,
+} from "./lib/managed-child-process.mts";
 import { parsePositiveInt } from "./lib/numeric-options.mjs";
 import {
   listPluginSdkDeclarationOutputs,
@@ -231,11 +234,17 @@ export function resolvePluginSdkTypeInputs(rootDir = repoRoot) {
   }
   const tsgoPath = resolveRepoToolBinPath("tsgo");
   ensureRepoToolNodeModulesLink(tsgoPath);
-  const result = spawnSync(
-    tsgoPath,
-    ["-p", "tsconfig.plugin-sdk.dts.json", "--listFilesOnly", "--noEmit"],
-    { cwd: rootDir, encoding: "utf8", maxBuffer: 16 * 1024 * 1024 },
-  );
+  const tsgo = createManagedCommandInvocation({
+    args: ["-p", "tsconfig.plugin-sdk.dts.json", "--listFilesOnly", "--noEmit"],
+    bin: tsgoPath,
+  });
+  const result = spawnSync(tsgo.command, tsgo.args, {
+    cwd: rootDir,
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+    shell: tsgo.shell,
+    windowsVerbatimArguments: tsgo.windowsVerbatimArguments,
+  });
   if (result.status !== 0 || result.error) {
     throw new Error(`Failed to derive plugin SDK type inputs: ${result.stderr || result.error}`);
   }
diff --git a/scripts/run-lint.mts b/scripts/run-lint.mts
index 79e8821d00d7..ee9b990657cd 100644
--- a/scripts/run-lint.mts
+++ b/scripts/run-lint.mts
@@ -46,11 +46,14 @@ if (uiI18nStatus !== 0) {
   } else {
     // Control UI CSS hygiene: plain stylesheets plus css`` templates in Lit
     // components. oxlint cannot see inside tagged CSS templates.
+    // Delegate like the steps above: the stylelint runner already resolves and
+    // launches the shim, so this pipeline never handles a tool path itself.
     process.exitCode = run(
-      resolveRepoToolBinPath("stylelint"),
+      process.execPath,
       [
-        "--config",
-        path.resolve("config", "stylelint.config.mjs"),
+        "--import",
+        tsxImportSpecifier,
+        path.resolve("scripts", "run-stylelint.mts"),
         "ui/src/**/*.css",
         "ui/src/**/*.ts",
       ],
diff --git a/scripts/run-stylelint.mts b/scripts/run-stylelint.mts
index c7e8de4617fc..7fea6636247e 100644
--- a/scripts/run-stylelint.mts
+++ b/scripts/run-stylelint.mts
@@ -5,14 +5,21 @@ import {
   ensureRepoToolNodeModulesLink,
   resolveRepoToolBinPath,
 } from "./lib/local-check-runtime.mts";
+import { createManagedCommandInvocation } from "./lib/managed-child-process.mts";
 
 const stylelintPath = resolveRepoToolBinPath("stylelint");
 ensureRepoToolNodeModulesLink(stylelintPath);
-const result = spawnSync(
-  stylelintPath,
-  ["--config", path.resolve("config", "stylelint.config.mjs"), ...process.argv.slice(2)],
-  { env: process.env, stdio: "inherit" },
-);
+const stylelint = createManagedCommandInvocation({
+  args: ["--config", path.resolve("config", "stylelint.config.mjs"), ...process.argv.slice(2)],
+  bin: stylelintPath,
+  env: process.env,
+});
+const result = spawnSync(stylelint.command, stylelint.args, {
+  env: process.env,
+  shell: stylelint.shell,
+  stdio: "inherit",
+  windowsVerbatimArguments: stylelint.windowsVerbatimArguments,
+});
 if (result.error) {
   throw result.error;
 }
diff --git a/test/scripts/managed-child-process.test.ts b/test/scripts/managed-child-process.test.ts
index a7038bdbdeab..9fbd2d01c71a 100644
--- a/test/scripts/managed-child-process.test.ts
+++ b/test/scripts/managed-child-process.test.ts
@@ -80,14 +80,19 @@ describe("managed-child-process", () => {
   it("uses Windows shell normalization when the platform override is win32", () => {
     expect(
       createManagedCommandSpawnSpec({
-        args: ["lint:scripts", "--", "scripts"],
-        bin: "pnpm.cmd",
+        args: ["-p", "tsconfig.plugin-sdk.dts.json", "--listFilesOnly", "--noEmit"],
+        bin: "C:\\repo\\node_modules\\.bin\\tsgo",
         comSpec: "C:\\Windows\\System32\\cmd.exe",
         env: {},
         platform: "win32",
       }),
     ).toEqual({
-      args: ["/d", "/s", "/c", "pnpm.cmd lint:scripts -- scripts"],
+      args: [
+        "/d",
+        "/s",
+        "/c",
+        "C:\\repo\\node_modules\\.bin\\tsgo -p tsconfig.plugin-sdk.dts.json --listFilesOnly --noEmit",
+      ],
       command: "C:\\Windows\\System32\\cmd.exe",
       options: {
         cwd: undefined,

From 1319e1e606525e8b764aac43eb817a90daa9efc5 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Fri, 21 Aug 2026 19:32:07 +0300
Subject: [PATCH 032/124] fix(providers): report request acceptance
 consistently (#126028)

* fix(providers): restore provider acceptance lifecycle

* fix(providers): cancel streams on acceptance failure

* test(amazon-bedrock): split stream lifecycle coverage

* refactor(providers): keep acceptance lifecycle private

* refactor(providers): make acceptance observation synchronous

* refactor(providers): narrow private observer safely

* fix(google): keep response hook within retry deadline

* test(ui): tolerate subpixel spacing variance

* test(ui): wait for durable draft before reload
---
 .../mantle-anthropic.runtime.test.ts          |  28 ++-
 .../mantle-anthropic.runtime.ts               |  10 +-
 .../stream.runtime.lifecycle.test.ts          | 142 +++++++++++
 .../amazon-bedrock/stream.runtime.test.ts     |  98 --------
 extensions/amazon-bedrock/stream.runtime.ts   |  14 +-
 .../anthropic-vertex/stream-runtime.test.ts   |  19 ++
 extensions/anthropic-vertex/stream-runtime.ts |   6 +-
 extensions/google/transport-stream.test.ts    | 166 +++++++++++++
 extensions/google/transport-stream.ts         | 105 +++++---
 extensions/ollama/src/stream-runtime.test.ts  |  25 ++
 extensions/ollama/src/stream.runtime.ts       |  52 +---
 packages/ai/src/providers/anthropic.ts        |   7 +-
 .../ai/src/providers/google-shared.test.ts    |  40 ++++
 packages/ai/src/providers/google-shared.ts    |  10 +-
 .../mistral-http-client.contract.test.ts      |  29 +++
 packages/ai/src/providers/mistral.test.ts     | 138 +++++++++++
 packages/ai/src/providers/mistral.ts          |  39 ++-
 ...openai-chatgpt-responses-streaming.test.ts |  55 +++++
 ...-chatgpt-responses.encrypted-retry.test.ts |  42 ++++
 .../openai-chatgpt-responses.retry.test.ts    |  17 +-
 .../src/providers/openai-chatgpt-responses.ts |  26 +-
 .../ai/src/providers/openai-completions.ts    |   4 +-
 .../src/providers/openai-responses-shared.ts  |   4 +-
 packages/ai/src/providers/simple-options.ts   |   4 +-
 .../anthropic-transport-stream.test.ts        |  80 ++++++-
 .../transports/anthropic-transport-stream.ts  |  33 ++-
 ...ompletions-transport.response-hook.test.ts |  59 ++++-
 .../openai-completions-transport.ts           |   4 +-
 .../src/transports/openai-responses-client.ts |  13 +-
 .../openai-responses-websocket-client.test.ts |  41 ++++
 .../src/transports/openai-transport-shared.ts |  10 +-
 ...transport-stream-shared.acceptance.test.ts | 143 +++++++++++
 .../src/transports/transport-stream-shared.ts | 225 ++++++++++++++++--
 ...attempt.model-diagnostic-lifecycle.test.ts |  38 ++-
 .../run/attempt.model-diagnostic-lifecycle.ts |  23 +-
 src/plugin-sdk/provider-transport-runtime.ts  |   6 +
 ...new-session-page.draft-handoff.e2e.test.ts |   2 +
 .../chat/chat-responsive.browser.test.ts      |   5 +-
 38 files changed, 1492 insertions(+), 270 deletions(-)
 create mode 100644 packages/ai/src/providers/mistral-http-client.contract.test.ts
 create mode 100644 packages/ai/src/transports/transport-stream-shared.acceptance.test.ts

diff --git a/extensions/amazon-bedrock-mantle/mantle-anthropic.runtime.test.ts b/extensions/amazon-bedrock-mantle/mantle-anthropic.runtime.test.ts
index 6fa24510593e..053a2c798eab 100644
--- a/extensions/amazon-bedrock-mantle/mantle-anthropic.runtime.test.ts
+++ b/extensions/amazon-bedrock-mantle/mantle-anthropic.runtime.test.ts
@@ -1,5 +1,9 @@
 import type { Model } from "openclaw/plugin-sdk/llm";
 // Amazon Bedrock Mantle tests cover mantle anthropic plugin behavior.
+import {
+  notifyProviderStreamOpened,
+  withProviderAcceptanceObserver,
+} from "openclaw/plugin-sdk/provider-transport-runtime";
 import { createRequireRecord } from "openclaw/plugin-sdk/test-fixtures";
 import { describe, expect, it, vi } from "vitest";
 import { createMantleAnthropicStreamFn } from "./mantle-anthropic.runtime.js";
@@ -54,19 +58,26 @@ function firstStreamOptions(deps: ReturnType<typeof createTestDeps>): Record<str
 }
 
 describe("createMantleAnthropicStreamFn", () => {
-  it("uses authToken bearer auth for Mantle Anthropic requests", () => {
+  it("uses authToken bearer auth for Mantle Anthropic requests", async () => {
     const stream = { kind: "anthropic-stream" };
     const model = createTestModel();
     const context = { messages: [] };
     const deps = createTestDeps();
     deps.stream.mockReturnValue(stream as never);
-
-    const result = createMantleAnthropicStreamFn(deps)(model, context, {
-      apiKey: "bedrock-bearer-token",
-      headers: {
-        "X-Caller": "caller-header",
+    const acceptanceObserver = vi.fn();
+    const onResponse = vi.fn();
+    const options = withProviderAcceptanceObserver(
+      {
+        apiKey: "bedrock-bearer-token",
+        onResponse,
+        headers: {
+          "X-Caller": "caller-header",
+        },
       },
-    });
+      acceptanceObserver,
+    );
+
+    const result = createMantleAnthropicStreamFn(deps)(model, context, options);
 
     expect(result).toBe(stream);
     const clientOptions = requireRecord(mockCallArg(deps.createClient), "client options");
@@ -87,6 +98,9 @@ describe("createMantleAnthropicStreamFn", () => {
       "bedrock-bearer-token",
     );
     expect(streamOptions.thinkingEnabled).toBe(false);
+    expect(streamOptions.onResponse).toBe(onResponse);
+    await notifyProviderStreamOpened({ options: streamOptions, cancelStream: vi.fn() });
+    expect(acceptanceObserver).toHaveBeenCalledWith({ kind: "provider_stream_opened" });
   });
 
   it("omits unsupported Opus 4.7 sampling and reasoning overrides", () => {
diff --git a/extensions/amazon-bedrock-mantle/mantle-anthropic.runtime.ts b/extensions/amazon-bedrock-mantle/mantle-anthropic.runtime.ts
index afaed5a55890..d88d5a69dda2 100644
--- a/extensions/amazon-bedrock-mantle/mantle-anthropic.runtime.ts
+++ b/extensions/amazon-bedrock-mantle/mantle-anthropic.runtime.ts
@@ -16,7 +16,10 @@ import {
   resolveClaudeOpus5ModelIdentity,
   resolveClaudeSonnet5ModelIdentity,
 } from "openclaw/plugin-sdk/provider-model-shared";
-import { buildGuardedModelFetch } from "openclaw/plugin-sdk/provider-transport-runtime";
+import {
+  buildGuardedModelFetch,
+  copyProviderAcceptanceObserver,
+} from "openclaw/plugin-sdk/provider-transport-runtime";
 
 const MANTLE_ANTHROPIC_BETA = "fine-grained-tool-streaming-2025-05-14";
 type AnthropicOptions = ConstructorParameters<typeof Anthropic>[0];
@@ -124,7 +127,7 @@ function buildMantleAnthropicBaseOptions(
   options: SimpleStreamOptions | undefined,
   apiKey: string,
 ) {
-  return {
+  return copyProviderAcceptanceObserver(options, {
     ...(requiresDefaultSampling(model) ? {} : { temperature: options?.temperature }),
     maxTokens:
       options?.maxTokens ||
@@ -136,9 +139,10 @@ function buildMantleAnthropicBaseOptions(
     cacheRetention: options?.cacheRetention,
     sessionId: options?.sessionId,
     onPayload: options?.onPayload,
+    onResponse: options?.onResponse,
     maxRetryDelayMs: options?.maxRetryDelayMs,
     metadata: options?.metadata,
-  };
+  });
 }
 
 function adjustMaxTokensForThinking(
diff --git a/extensions/amazon-bedrock/stream.runtime.lifecycle.test.ts b/extensions/amazon-bedrock/stream.runtime.lifecycle.test.ts
index cef472c1a9a0..b8bab415c3f5 100644
--- a/extensions/amazon-bedrock/stream.runtime.lifecycle.test.ts
+++ b/extensions/amazon-bedrock/stream.runtime.lifecycle.test.ts
@@ -3,6 +3,7 @@ import {
   ConversationRole,
   StopReason as BedrockStopReason,
 } from "@aws-sdk/client-bedrock-runtime";
+import { withProviderAcceptanceObserver } from "openclaw/plugin-sdk/provider-transport-runtime";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { streamSimpleBedrock } from "./stream.runtime.js";
 
@@ -23,6 +24,26 @@ async function* events(items: unknown[]) {
   yield* items;
 }
 
+function streamBedrockForTest(options: Parameters<typeof streamSimpleBedrock>[2] = {}) {
+  return streamSimpleBedrock(
+    model as never,
+    { messages: [{ role: "user", content: "Hello", timestamp: 0 }] } as never,
+    options,
+  );
+}
+
+function expectDestroyedClient(
+  send: ReturnType<typeof vi.spyOn>,
+  destroy: ReturnType<typeof vi.spyOn>,
+) {
+  expect(send).toHaveBeenCalledOnce();
+  expect(destroy).toHaveBeenCalledOnce();
+  expect(destroy.mock.contexts[0]).toBe(send.mock.contexts[0]);
+  expect(destroy.mock.invocationCallOrder[0]).toBeGreaterThan(
+    send.mock.invocationCallOrder[0] ?? 0,
+  );
+}
+
 afterEach(() => {
   vi.restoreAllMocks();
 });
@@ -109,3 +130,124 @@ describe("Bedrock provider-owned stream lifecycle", () => {
     }
   });
 });
+
+describe("Bedrock stream client lifecycle", () => {
+  it("destroys the client after a successful stream", async () => {
+    let markStreamBlocked!: () => void;
+    const streamBlocked = new Promise<void>((resolve) => {
+      markStreamBlocked = resolve;
+    });
+    let releaseStream!: () => void;
+    const streamReleased = new Promise<void>((resolve) => {
+      releaseStream = resolve;
+    });
+    async function* successfulStream() {
+      yield { messageStart: { role: ConversationRole.ASSISTANT } };
+      markStreamBlocked();
+      await streamReleased;
+      yield { messageStop: { stopReason: BedrockStopReason.END_TURN } };
+    }
+    const send = vi.spyOn(BedrockRuntimeClient.prototype, "send").mockResolvedValue({
+      $metadata: { httpStatusCode: 200, requestId: "bedrock-request-1" },
+      stream: successfulStream(),
+    } as never);
+    const destroy = vi.spyOn(BedrockRuntimeClient.prototype, "destroy");
+    const acceptanceObserver = vi.fn();
+    const onResponse = vi.fn();
+    const options = withProviderAcceptanceObserver({ onResponse }, acceptanceObserver);
+
+    const resultPromise = streamBedrockForTest(options).result();
+    await streamBlocked;
+    expect(destroy).not.toHaveBeenCalled();
+
+    releaseStream();
+    const result = await resultPromise;
+
+    expect(result.stopReason).toBe("stop");
+    expect(acceptanceObserver).toHaveBeenCalledWith({
+      kind: "http_response",
+      status: 200,
+      headers: { "x-amzn-requestid": "bedrock-request-1" },
+    });
+    expect(onResponse).toHaveBeenCalledWith(
+      { status: 200, headers: { "x-amzn-requestid": "bedrock-request-1" } },
+      expect.objectContaining({ provider: "amazon-bedrock" }),
+    );
+    expectDestroyedClient(send, destroy);
+  });
+
+  it("cancels an unread stream when provider acceptance fails", async () => {
+    const close = vi.fn(async () => ({ done: true as const, value: undefined }));
+    const responseIterator = {
+      next: vi.fn(() => new Promise<IteratorResult<never>>(() => {})),
+      return: close,
+      [Symbol.asyncIterator]() {
+        return this;
+      },
+    };
+    const send = vi.spyOn(BedrockRuntimeClient.prototype, "send").mockResolvedValue({
+      $metadata: { httpStatusCode: 200 },
+      stream: responseIterator,
+    } as never);
+    const destroy = vi.spyOn(BedrockRuntimeClient.prototype, "destroy");
+    const hookError = new Error("acceptance observer failed");
+    const options = withProviderAcceptanceObserver({}, () => {
+      throw hookError;
+    });
+
+    const result = await streamBedrockForTest(options).result();
+
+    expect(result).toMatchObject({
+      stopReason: "error",
+      errorMessage: "acceptance observer failed",
+    });
+    expect(close).toHaveBeenCalledOnce();
+    expectDestroyedClient(send, destroy);
+  });
+
+  it("destroys the client after a provider error", async () => {
+    const send = vi
+      .spyOn(BedrockRuntimeClient.prototype, "send")
+      .mockRejectedValue(new Error("synthetic provider failure"));
+    const destroy = vi.spyOn(BedrockRuntimeClient.prototype, "destroy");
+
+    const result = await streamBedrockForTest().result();
+
+    expect(result.stopReason).toBe("error");
+    expect(result.errorMessage).toBe("synthetic provider failure");
+    expectDestroyedClient(send, destroy);
+  });
+
+  it("destroys the client when response stream iteration fails", async () => {
+    async function* failingStream() {
+      yield { messageStart: { role: ConversationRole.ASSISTANT } };
+      throw new Error("synthetic iterator failure");
+    }
+    const send = vi.spyOn(BedrockRuntimeClient.prototype, "send").mockResolvedValue({
+      $metadata: { httpStatusCode: 200 },
+      stream: failingStream(),
+    } as never);
+    const destroy = vi.spyOn(BedrockRuntimeClient.prototype, "destroy");
+
+    const result = await streamBedrockForTest().result();
+
+    expect(result.stopReason).toBe("error");
+    expect(result.errorMessage).toBe("synthetic iterator failure");
+    expectDestroyedClient(send, destroy);
+  });
+
+  it("destroys the client after an aborted request", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const send = vi
+      .spyOn(BedrockRuntimeClient.prototype, "send")
+      .mockRejectedValue(new Error("synthetic abort"));
+    const destroy = vi.spyOn(BedrockRuntimeClient.prototype, "destroy");
+
+    const result = await streamBedrockForTest({ signal: controller.signal }).result();
+
+    expect(result.stopReason).toBe("aborted");
+    expect(result.errorMessage).toBe("synthetic abort");
+    expectDestroyedClient(send, destroy);
+  });
+});
diff --git a/extensions/amazon-bedrock/stream.runtime.test.ts b/extensions/amazon-bedrock/stream.runtime.test.ts
index ebf0bfd6cbcc..a9208050e2f4 100644
--- a/extensions/amazon-bedrock/stream.runtime.test.ts
+++ b/extensions/amazon-bedrock/stream.runtime.test.ts
@@ -86,104 +86,6 @@ afterEach(() => {
   vi.restoreAllMocks();
 });
 
-describe("Bedrock stream client lifecycle", () => {
-  const context = {
-    messages: [{ role: "user", content: "Hello", timestamp: 0 }],
-  } as never;
-
-  function expectDestroyedClient(
-    send: ReturnType<typeof vi.spyOn>,
-    destroy: ReturnType<typeof vi.spyOn>,
-  ) {
-    expect(send).toHaveBeenCalledOnce();
-    expect(destroy).toHaveBeenCalledOnce();
-    expect(destroy.mock.contexts[0]).toBe(send.mock.contexts[0]);
-    expect(destroy.mock.invocationCallOrder[0]).toBeGreaterThan(
-      send.mock.invocationCallOrder[0] ?? 0,
-    );
-  }
-
-  it("destroys the client after a successful stream", async () => {
-    let markStreamBlocked!: () => void;
-    const streamBlocked = new Promise<void>((resolve) => {
-      markStreamBlocked = resolve;
-    });
-    let releaseStream!: () => void;
-    const streamReleased = new Promise<void>((resolve) => {
-      releaseStream = resolve;
-    });
-    async function* successfulStream() {
-      yield { messageStart: { role: ConversationRole.ASSISTANT } };
-      markStreamBlocked();
-      await streamReleased;
-      yield { messageStop: { stopReason: BedrockStopReason.END_TURN } };
-    }
-    const send = vi.spyOn(BedrockRuntimeClient.prototype, "send").mockResolvedValue({
-      $metadata: { httpStatusCode: 200 },
-      stream: successfulStream(),
-    } as never);
-    const destroy = vi.spyOn(BedrockRuntimeClient.prototype, "destroy");
-
-    const resultPromise = streamBedrockForTest(bedrockModel({}), context).result();
-    await streamBlocked;
-    expect(destroy).not.toHaveBeenCalled();
-
-    releaseStream();
-    const result = await resultPromise;
-
-    expect(result.stopReason).toBe("stop");
-    expectDestroyedClient(send, destroy);
-  });
-
-  it("destroys the client after a provider error", async () => {
-    const send = vi
-      .spyOn(BedrockRuntimeClient.prototype, "send")
-      .mockRejectedValue(new Error("synthetic provider failure"));
-    const destroy = vi.spyOn(BedrockRuntimeClient.prototype, "destroy");
-
-    const result = await streamBedrockForTest(bedrockModel({}), context).result();
-
-    expect(result.stopReason).toBe("error");
-    expect(result.errorMessage).toBe("synthetic provider failure");
-    expectDestroyedClient(send, destroy);
-  });
-
-  it("destroys the client when response stream iteration fails", async () => {
-    async function* failingStream() {
-      yield { messageStart: { role: ConversationRole.ASSISTANT } };
-      throw new Error("synthetic iterator failure");
-    }
-    const send = vi.spyOn(BedrockRuntimeClient.prototype, "send").mockResolvedValue({
-      $metadata: { httpStatusCode: 200 },
-      stream: failingStream(),
-    } as never);
-    const destroy = vi.spyOn(BedrockRuntimeClient.prototype, "destroy");
-
-    const result = await streamBedrockForTest(bedrockModel({}), context).result();
-
-    expect(result.stopReason).toBe("error");
-    expect(result.errorMessage).toBe("synthetic iterator failure");
-    expectDestroyedClient(send, destroy);
-  });
-
-  it("destroys the client after an aborted request", async () => {
-    const controller = new AbortController();
-    controller.abort();
-    const send = vi
-      .spyOn(BedrockRuntimeClient.prototype, "send")
-      .mockRejectedValue(new Error("synthetic abort"));
-    const destroy = vi.spyOn(BedrockRuntimeClient.prototype, "destroy");
-
-    const result = await streamBedrockForTest(bedrockModel({}), context, {
-      signal: controller.signal,
-    }).result();
-
-    expect(result.stopReason).toBe("aborted");
-    expect(result.errorMessage).toBe("synthetic abort");
-    expectDestroyedClient(send, destroy);
-  });
-});
-
 describe("Bedrock inbound image base64", () => {
   const model = () => bedrockModel({ input: ["text", "image"] });
   const userImage = (data: string) =>
diff --git a/extensions/amazon-bedrock/stream.runtime.ts b/extensions/amazon-bedrock/stream.runtime.ts
index fa8cd325460e..b73e67ec1c3b 100644
--- a/extensions/amazon-bedrock/stream.runtime.ts
+++ b/extensions/amazon-bedrock/stream.runtime.ts
@@ -73,6 +73,7 @@ import {
 import {
   describeToolResultMediaPlaceholder,
   finalizeTerminalToolCallArguments,
+  notifyProviderHttpMetadata,
 } from "openclaw/plugin-sdk/provider-transport-runtime";
 import { isRecord, normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { supportsBedrockPromptCaching, type BedrockOptions } from "./bedrock-options.js";
@@ -289,19 +290,24 @@ const streamBedrock: StreamFunction<"bedrock-converse-stream", BedrockOptions> =
       const command = new ConverseStreamCommand(commandInput);
 
       const response = await client.send(command, { abortSignal: options.signal });
+      const responseIterator = response.stream![Symbol.asyncIterator]();
       if (response.$metadata.httpStatusCode !== undefined) {
         const responseHeaders: Record<string, string> = {};
         if (response.$metadata.requestId) {
           responseHeaders["x-amzn-requestid"] = response.$metadata.requestId;
         }
-        await options?.onResponse?.(
-          { status: response.$metadata.httpStatusCode, headers: responseHeaders },
+        await notifyProviderHttpMetadata({
+          options,
+          response: { status: response.$metadata.httpStatusCode, headers: responseHeaders },
           model,
-        );
+          cancelStream: async () => {
+            await responseIterator.return?.();
+          },
+        });
       }
 
       let sawMessageStop = false;
-      for await (const item of response.stream!) {
+      for await (const item of { [Symbol.asyncIterator]: () => responseIterator }) {
         if (item.messageStart) {
           if (item.messageStart.role !== ConversationRole.ASSISTANT) {
             throw new Error(
diff --git a/extensions/anthropic-vertex/stream-runtime.test.ts b/extensions/anthropic-vertex/stream-runtime.test.ts
index 2cd043fba24a..9a1c98705052 100644
--- a/extensions/anthropic-vertex/stream-runtime.test.ts
+++ b/extensions/anthropic-vertex/stream-runtime.test.ts
@@ -5,6 +5,10 @@ import { createServer } from "node:http";
 import os from "node:os";
 import path from "node:path";
 import { createAssistantMessageEventStream, type Model } from "openclaw/plugin-sdk/llm";
+import {
+  notifyProviderStreamOpened,
+  withProviderAcceptanceObserver,
+} from "openclaw/plugin-sdk/provider-transport-runtime";
 import { beforeAll, describe, expect, it, vi } from "vitest";
 import type { AnthropicVertexStreamDeps } from "./stream-runtime.js";
 
@@ -541,6 +545,21 @@ describe("createAnthropicVertexStreamFn", () => {
     expect(transportOptions).not.toHaveProperty("temperature");
   });
 
+  it("forwards the private acceptance observer to the shared Anthropic transport", async () => {
+    const { deps, streamAnthropicMock } = createStreamDeps();
+    const streamFn = createAnthropicVertexStreamFn("vertex-project", "us-east5", undefined, deps);
+    const acceptanceObserver = vi.fn();
+    const onResponse = vi.fn();
+    const options = withProviderAcceptanceObserver({ onResponse }, acceptanceObserver);
+
+    void streamFn(makeModel({ id: "claude-sonnet-4-6" }), { messages: [] }, options);
+
+    const transportOptions = streamTransportOptions(streamAnthropicMock);
+    expect(transportOptions.onResponse).toBe(onResponse);
+    await notifyProviderStreamOpened({ options: transportOptions, cancelStream: vi.fn() });
+    expect(acceptanceObserver).toHaveBeenCalledWith({ kind: "provider_stream_opened" });
+  });
+
   it("keeps already-budgeted cache_control markers intact when forwarding payload hooks", async () => {
     const { deps, streamAnthropicMock } = createStreamDeps();
     const onPayload = vi.fn(async (payload: unknown) => payload);
diff --git a/extensions/anthropic-vertex/stream-runtime.ts b/extensions/anthropic-vertex/stream-runtime.ts
index 572e4e523ddd..5a950879a826 100644
--- a/extensions/anthropic-vertex/stream-runtime.ts
+++ b/extensions/anthropic-vertex/stream-runtime.ts
@@ -23,6 +23,7 @@ import {
   supportsClaudeNativeMaxEffort,
   supportsClaudeNativeXhighEffort,
 } from "openclaw/plugin-sdk/provider-model-shared";
+import { copyProviderAcceptanceObserver } from "openclaw/plugin-sdk/provider-transport-runtime";
 import { EnvHttpProxyAgent, fetch as undiciFetch } from "undici";
 import {
   resolveAnthropicVertexAdcCredentials,
@@ -219,7 +220,7 @@ export function createAnthropicVertexStreamFn(
       isClaudeMythos5Model(contractModelId)
         ? undefined
         : options?.temperature;
-    const opts: AnthropicVertexTransportOptions = {
+    const opts: AnthropicVertexTransportOptions = copyProviderAcceptanceObserver(options, {
       client,
       ...(temperature !== undefined ? { temperature } : {}),
       ...(maxTokens !== undefined ? { maxTokens } : {}),
@@ -231,9 +232,10 @@ export function createAnthropicVertexStreamFn(
       // cache boundary and budgets all cache_control markers; re-applying the
       // payload policy here marked the uncached suffix and breached the 4-marker cap.
       onPayload: options?.onPayload,
+      onResponse: options?.onResponse,
       maxRetryDelayMs: options?.maxRetryDelayMs,
       metadata: options?.metadata,
-    };
+    });
 
     if (reasoning === "off") {
       opts.thinkingEnabled = false;
diff --git a/extensions/google/transport-stream.test.ts b/extensions/google/transport-stream.test.ts
index 7c6f00eb4d65..39b1e2ede421 100644
--- a/extensions/google/transport-stream.test.ts
+++ b/extensions/google/transport-stream.test.ts
@@ -6,6 +6,7 @@ import { gzipSync } from "node:zlib";
 import { expectDefined } from "@openclaw/normalization-core";
 import { toErrorObject as toLintErrorObject } from "openclaw/plugin-sdk/error-runtime";
 import type { Model, ProviderContext } from "openclaw/plugin-sdk/llm";
+import { withProviderAcceptanceObserver } from "openclaw/plugin-sdk/provider-transport-runtime";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { resetGoogleVertexAdcState } from "./google-oauth.test-support.js";
 
@@ -630,6 +631,53 @@ describe("google transport stream", () => {
     expect(guardedFetchMock).not.toHaveBeenCalled();
   });
 
+  it("reports the real HTTP response before consuming Gemini SSE output", async () => {
+    mockGoogleTextResponse();
+    const acceptanceObserver = vi.fn();
+    const onResponse = vi.fn();
+    const options = withProviderAcceptanceObserver({ onResponse }, acceptanceObserver);
+
+    const result = await runGeminiStreamResult({ options });
+
+    expect(result.stopReason).toBe("stop");
+    expect(acceptanceObserver).toHaveBeenCalledWith({
+      kind: "http_response",
+      status: 200,
+      headers: { "content-type": "text/event-stream" },
+    });
+    expect(onResponse).toHaveBeenCalledWith(
+      { status: 200, headers: { "content-type": "text/event-stream" } },
+      expect.objectContaining({ provider: "google" }),
+    );
+  });
+
+  it("reports rejected HTTP responses without marking them accepted", async () => {
+    guardedFetchMock.mockResolvedValueOnce(
+      new Response('{"error":{"message":"rate limited"}}', {
+        status: 429,
+        headers: {
+          "content-type": "application/json",
+          "x-request-id": "req-rejected",
+        },
+      }),
+    );
+    const acceptanceObserver = vi.fn();
+    const onResponse = vi.fn();
+    const options = withProviderAcceptanceObserver({ onResponse }, acceptanceObserver);
+
+    const result = await runGeminiStreamResult({ options });
+
+    expect(result.stopReason).toBe("error");
+    expect(acceptanceObserver).not.toHaveBeenCalled();
+    expect(onResponse).toHaveBeenCalledWith(
+      {
+        status: 429,
+        headers: expect.objectContaining({ "x-request-id": "req-rejected" }),
+      },
+      expect.objectContaining({ provider: "google" }),
+    );
+  });
+
   it("uses the guarded fetch transport and parses Gemini SSE output", async () => {
     guardedFetchMock.mockResolvedValueOnce(
       buildSseResponse([
@@ -1419,6 +1467,124 @@ describe("google transport stream", () => {
     },
   );
 
+  it("does not retry when provider acceptance observation fails", async () => {
+    vi.stubEnv("OPENCLAW_GOOGLE_GEMINI_FIRST_RESPONSE_RETRY_MS", "10");
+    let cancelCalled = false;
+    guardedFetchMock.mockResolvedValueOnce(
+      buildOpenRawSseResponse({
+        sse: 'data: {"candidates":[{"finishReason":"STOP"}]}\n\n',
+        onCancel: () => {
+          cancelCalled = true;
+        },
+      }),
+    );
+
+    const options = withProviderAcceptanceObserver({ reasoning: "high" }, () => {
+      throw new Error("acceptance observer failed");
+    });
+    const result = await runGeminiStreamResult({
+      model: buildGeminiModel({ id: "gemini-3.1-pro-preview" }),
+      options,
+    });
+
+    expect(result).toMatchObject({
+      stopReason: "error",
+      errorMessage: "acceptance observer failed",
+    });
+    expect(guardedFetchMock).toHaveBeenCalledOnce();
+    expect(cancelCalled).toBe(true);
+  });
+
+  it("aborts a pending response callback without retrying", async () => {
+    vi.stubEnv("OPENCLAW_GOOGLE_GEMINI_FIRST_RESPONSE_RETRY_MS", "1000");
+    const controller = new AbortController();
+    const cancel = vi.fn();
+    guardedFetchMock.mockResolvedValueOnce(
+      buildOpenRawSseResponse({
+        sse: 'data: {"candidates":[{"finishReason":"STOP"}]}\n\n',
+        onCancel: cancel,
+      }),
+    );
+    let markHookStarted!: () => void;
+    const hookStarted = new Promise<void>((resolve) => {
+      markHookStarted = resolve;
+    });
+    const onResponse = vi.fn(() => {
+      markHookStarted();
+      return new Promise<void>(() => {});
+    });
+    const options = {
+      reasoning: "high",
+      signal: controller.signal,
+      onResponse,
+    };
+    const resultPromise = runGeminiStreamResult({
+      model: buildGeminiModel({ id: "gemini-3.1-pro-preview" }),
+      options,
+    });
+    await hookStarted;
+    controller.abort(
+      Object.assign(new Error("operator canceled the request"), {
+        code: "OPERATOR_CANCELLED",
+      }),
+    );
+
+    await expect(resultPromise).resolves.toMatchObject({
+      stopReason: "aborted",
+      errorCode: "OPERATOR_CANCELLED",
+      errorMessage: "operator canceled the request",
+    });
+    expect(onResponse).toHaveBeenCalledOnce();
+    expect(guardedFetchMock).toHaveBeenCalledOnce();
+    expect(cancel).toHaveBeenCalledOnce();
+  });
+
+  it("retries when a pending response callback reaches the Gemini first-response deadline", async () => {
+    vi.stubEnv("OPENCLAW_GOOGLE_GEMINI_FIRST_RESPONSE_RETRY_MS", "10");
+    const controller = new AbortController();
+    const cancel = vi.fn();
+    guardedFetchMock
+      .mockResolvedValueOnce(
+        buildOpenRawSseResponse({
+          sse: 'data: {"candidates":[{"finishReason":"STOP"}]}\n\n',
+          onCancel: cancel,
+        }),
+      )
+      .mockResolvedValueOnce(
+        buildSseResponse([
+          {
+            candidates: [{ content: { parts: [{ text: "recovered" }] }, finishReason: "STOP" }],
+          },
+        ]),
+      );
+    let responseCount = 0;
+    const onResponse = vi.fn(() => {
+      responseCount += 1;
+      return responseCount === 1 ? new Promise<void>(() => {}) : undefined;
+    });
+    const safetyTimeout = setTimeout(() => {
+      controller.abort(new Error("test safety deadline reached"));
+    }, 5000);
+
+    try {
+      const result = await runGeminiStreamResult({
+        model: buildGeminiModel({ id: "gemini-3.1-pro-preview" }),
+        options: {
+          reasoning: "high",
+          signal: controller.signal,
+          onResponse,
+        },
+      });
+
+      expect(result.content).toEqual([{ type: "text", text: "recovered" }]);
+      expect(onResponse).toHaveBeenCalledTimes(2);
+      expect(guardedFetchMock).toHaveBeenCalledTimes(2);
+      expect(cancel).toHaveBeenCalledOnce();
+    } finally {
+      clearTimeout(safetyTimeout);
+    }
+  });
+
   it("keeps oversized-video shedding in the Gemini 3 retry payload", async () => {
     vi.stubEnv("OPENCLAW_GOOGLE_GEMINI_FIRST_RESPONSE_RETRY_MS", "10");
     guardedFetchMock
diff --git a/extensions/google/transport-stream.ts b/extensions/google/transport-stream.ts
index 84499320a02a..62019047d947 100644
--- a/extensions/google/transport-stream.ts
+++ b/extensions/google/transport-stream.ts
@@ -34,6 +34,7 @@ import {
   failTransportStream,
   finalizeTransportStream,
   mergeTransportHeaders,
+  notifyProviderHttpResponse,
   sanitizeTransportPayloadText,
   sortPromptCacheToolsByName,
   stripSystemPromptCacheBoundary,
@@ -1052,9 +1053,10 @@ function createChildSignal(parent: AbortSignal | undefined, timeoutMs: number) {
       parent.addEventListener("abort", abortFromParent, { once: true });
     }
   }
-  if (timeoutMs > 0) {
+  if (!controller.signal.aborted && timeoutMs > 0) {
     timeout = setTimeout(() => {
       timedOut = true;
+      timeout = undefined;
       controller.abort(new Error("Google Gemini first response retry deadline reached"));
     }, timeoutMs);
     timeout.unref?.();
@@ -1104,6 +1106,20 @@ type GoogleSseAttempt =
     }
   | { type: "timeout" };
 
+async function notifyGoogleTransportHttpResponse(
+  model: GoogleTransportModel,
+  options: GoogleTransportOptions | undefined,
+  response: Response,
+  signal?: AbortSignal,
+): Promise<void> {
+  await notifyProviderHttpResponse({
+    options,
+    response,
+    model: canonicalGoogleModel(model),
+    signal,
+  });
+}
+
 async function openGoogleSseAttempt(params: {
   guardedFetch: ReturnType<typeof buildGuardedModelFetch>;
   url: string;
@@ -1113,44 +1129,63 @@ async function openGoogleSseAttempt(params: {
   parentSignal?: AbortSignal;
   firstResponseTimeoutMs: number;
   errorPrefix: string;
+  model: GoogleTransportModel;
+  options: GoogleTransportOptions | undefined;
 }): Promise<GoogleSseAttempt> {
   const attemptSignal =
     params.firstResponseTimeoutMs > 0
       ? createChildSignal(params.parentSignal, params.firstResponseTimeoutMs)
       : undefined;
   const signal = attemptSignal?.signal ?? params.parentSignal;
-  try {
-    const response = await params.guardedFetch(params.url, {
-      method: "POST",
-      headers: params.headers,
-      body: serializeGoogleRequest(params.request, params.videoSlots),
-      signal,
-    });
-    if (!response.ok) {
-      throw await createProviderHttpError(response, params.errorPrefix);
-    }
-    const chunks = parseGoogleSseChunks(response, signal);
-    const iterator = chunks[Symbol.asyncIterator]();
-    const first = await iterator.next();
-    attemptSignal?.clearDeadline();
-    if (first.done) {
-      return {
-        type: "ready",
-        chunks: iteratorToAsyncGenerator(iterator, attemptSignal?.cleanup),
-      };
-    }
-    return {
-      type: "ready",
-      firstChunk: first.value,
-      chunks: iteratorToAsyncGenerator(iterator, attemptSignal?.cleanup),
-    };
-  } catch (error) {
+  const handleTimedOperationError = (error: unknown): GoogleSseAttempt => {
     attemptSignal?.cleanup();
     if (attemptSignal?.timedOut() && !params.parentSignal?.aborted) {
       return { type: "timeout" };
     }
     throw error;
+  };
+  let response: Response;
+  try {
+    response = await params.guardedFetch(params.url, {
+      method: "POST",
+      headers: params.headers,
+      body: serializeGoogleRequest(params.request, params.videoSlots),
+      signal,
+    });
+  } catch (error) {
+    return handleTimedOperationError(error);
   }
+  try {
+    // Response hooks share the first-response deadline. A stalled hook must cancel
+    // the unread body and enter the same Gemini fallback as a stalled fetch or body.
+    await notifyGoogleTransportHttpResponse(params.model, params.options, response, signal);
+  } catch (error) {
+    return handleTimedOperationError(error);
+  }
+  if (!response.ok) {
+    attemptSignal?.cleanup();
+    throw await createProviderHttpError(response, params.errorPrefix);
+  }
+  const chunks = parseGoogleSseChunks(response, signal);
+  const iterator = chunks[Symbol.asyncIterator]();
+  let first: IteratorResult<GoogleSseChunk>;
+  try {
+    first = await iterator.next();
+  } catch (error) {
+    return handleTimedOperationError(error);
+  }
+  attemptSignal?.clearDeadline();
+  if (first.done) {
+    return {
+      type: "ready",
+      chunks: iteratorToAsyncGenerator(iterator, attemptSignal?.cleanup),
+    };
+  }
+  return {
+    type: "ready",
+    firstChunk: first.value,
+    chunks: iteratorToAsyncGenerator(iterator, attemptSignal?.cleanup),
+  };
 }
 
 async function openGoogleSseChunks(params: {
@@ -1174,6 +1209,12 @@ async function openGoogleSseChunks(params: {
       body: serializeGoogleRequest(params.request, params.videoSlots),
       signal: params.options?.signal,
     });
+    await notifyGoogleTransportHttpResponse(
+      params.model,
+      params.options,
+      response,
+      params.options?.signal,
+    );
     if (!response.ok) {
       throw await createProviderHttpError(response, errorPrefix);
     }
@@ -1191,6 +1232,12 @@ async function openGoogleSseChunks(params: {
       body: serializeGoogleRequest(params.request, params.videoSlots),
       signal: params.options?.signal,
     });
+    await notifyGoogleTransportHttpResponse(
+      params.model,
+      params.options,
+      response,
+      params.options?.signal,
+    );
     if (!response.ok) {
       throw await createProviderHttpError(response, errorPrefix);
     }
@@ -1209,6 +1256,8 @@ async function openGoogleSseChunks(params: {
     parentSignal: params.options?.signal,
     firstResponseTimeoutMs: retryMs,
     errorPrefix,
+    model: params.model,
+    options: params.options,
   });
   if (firstAttempt.type === "ready") {
     return firstAttempt;
@@ -1229,6 +1278,8 @@ async function openGoogleSseChunks(params: {
     parentSignal: params.options?.signal,
     firstResponseTimeoutMs: 0,
     errorPrefix,
+    model: params.model,
+    options: params.options,
   });
   if (retryAttempt.type === "timeout") {
     throw new Error("Google Gemini first response retry timed out unexpectedly");
diff --git a/extensions/ollama/src/stream-runtime.test.ts b/extensions/ollama/src/stream-runtime.test.ts
index e297b341604c..239f194fe913 100644
--- a/extensions/ollama/src/stream-runtime.test.ts
+++ b/extensions/ollama/src/stream-runtime.test.ts
@@ -1,5 +1,6 @@
 import { expectDefined } from "@openclaw/normalization-core";
 // Ollama tests cover stream runtime plugin behavior.
+import { withProviderAcceptanceObserver } from "openclaw/plugin-sdk/provider-transport-runtime";
 import { createRequireRecord } from "openclaw/plugin-sdk/test-fixtures";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
@@ -456,6 +457,30 @@ describe("createConfiguredOllamaCompatStreamWrapper", () => {
     },
   );
 
+  it("reports the real HTTP response before consuming native Ollama output", async () => {
+    await withSuccessfulOllamaFetch(async () => {
+      const acceptanceObserver = vi.fn();
+      const onResponse = vi.fn();
+      const options = withProviderAcceptanceObserver({ onResponse }, acceptanceObserver);
+      const stream = await createOllamaTestStream({
+        baseUrl: "http://ollama-host:11434",
+        options,
+      });
+
+      await collectStreamEvents(stream);
+
+      expect(acceptanceObserver).toHaveBeenCalledWith({
+        kind: "http_response",
+        status: 200,
+        headers: { "content-type": "application/x-ndjson" },
+      });
+      expect(onResponse).toHaveBeenCalledWith(
+        { status: 200, headers: { "content-type": "application/x-ndjson" } },
+        expect.objectContaining({ provider: "custom-ollama" }),
+      );
+    });
+  });
+
   it("passes resolved provider request timeouts to native Ollama chat fetches", async () => {
     await withMockNdjsonFetch(
       [
diff --git a/extensions/ollama/src/stream.runtime.ts b/extensions/ollama/src/stream.runtime.ts
index 702d853d0b33..a1803ba7ee2f 100644
--- a/extensions/ollama/src/stream.runtime.ts
+++ b/extensions/ollama/src/stream.runtime.ts
@@ -26,6 +26,7 @@ import {
   formatToolResultText,
   isImageWithMediaPayload,
   MALFORMED_STREAMING_FRAGMENT_ERROR_MESSAGE,
+  notifyProviderHttpResponse,
   parseTerminalToolCallArguments,
 } from "openclaw/plugin-sdk/provider-transport-runtime";
 import { fetchWithSsrFGuard } from "openclaw/plugin-sdk/ssrf-runtime";
@@ -80,36 +81,6 @@ function throwIfOllamaStreamAborted(signal?: AbortSignal): void {
   }
 }
 
-async function runOllamaResponseHook(params: {
-  hook: (() => void | Promise<void>) | undefined;
-  signal: AbortSignal | undefined;
-}): Promise<void> {
-  const { hook, signal } = params;
-  if (!hook) {
-    return;
-  }
-  throwIfOllamaStreamAborted(signal);
-  if (!signal) {
-    await hook();
-    return;
-  }
-  let onAbort: (() => void) | undefined;
-  try {
-    await Promise.race([
-      Promise.resolve().then(hook),
-      new Promise<never>((_resolve, reject) => {
-        onAbort = () => reject(new Error("Request was aborted"));
-        signal.addEventListener("abort", onAbort, { once: true });
-      }),
-    ]);
-  } finally {
-    if (onAbort) {
-      signal.removeEventListener("abort", onAbort);
-    }
-  }
-  throwIfOllamaStreamAborted(signal);
-}
-
 function createOllamaStreamCooperativeScheduler(
   signal?: AbortSignal,
 ): OllamaStreamCooperativeScheduler {
@@ -1079,26 +1050,7 @@ function createRawOllamaStreamFn(
         });
 
         try {
-          const responseHook = options?.onResponse;
-          try {
-            await runOllamaResponseHook({
-              hook: responseHook
-                ? () =>
-                    responseHook(
-                      {
-                        status: response.status,
-                        headers: Object.fromEntries(response.headers.entries()),
-                      },
-                      model,
-                    )
-                : undefined,
-              signal: options?.signal,
-            });
-          } catch (error) {
-            // A pending body cancel must not stall release or the terminal error.
-            void response.body?.cancel().catch(() => undefined);
-            throw error;
-          }
+          await notifyProviderHttpResponse({ options, response, model });
           if (!response.ok) {
             const errorText = await readResponseTextLimited(
               response,
diff --git a/packages/ai/src/providers/anthropic.ts b/packages/ai/src/providers/anthropic.ts
index 2d7f81835804..acc658d32ee5 100644
--- a/packages/ai/src/providers/anthropic.ts
+++ b/packages/ai/src/providers/anthropic.ts
@@ -31,6 +31,7 @@ import {
 import { applyAnthropicCacheControlToMessages } from "../transports/anthropic-payload-policy.js";
 import {
   finalizeTerminalToolCallArguments,
+  notifyProviderHttpResponse,
   transportAbortError,
 } from "../transports/transport-stream-shared.js";
 import { MALFORMED_STREAMING_FRAGMENT_ERROR_MESSAGE } from "../transports/transport-utils.js";
@@ -52,7 +53,6 @@ import type {
 } from "../types.js";
 import { createDeferredEventBuffer } from "../utils/deferred-event-buffer.js";
 import { AssistantMessageEventStream } from "../utils/event-stream.js";
-import { headersToRecord } from "../utils/headers.js";
 import { parseJsonWithRepair, parseStreamingJson } from "../utils/json-parse.js";
 import { notifyLlmRequestActivity } from "../utils/llm-request-activity.js";
 import { projectProviderError } from "../utils/provider-error.js";
@@ -425,10 +425,7 @@ export const streamAnthropic: StreamFunction<"anthropic-messages", AnthropicComp
       const response = await client.messages
         .create({ ...params, stream: true }, sdkRequestOptions)
         .asResponse();
-      await requestOptions?.onResponse?.(
-        { status: response.status, headers: headersToRecord(response.headers) },
-        model,
-      );
+      await notifyProviderHttpResponse({ options: requestOptions, response, model });
 
       type Block = (ThinkingContent | TextContent | (ToolCall & { partialJson?: string })) & {
         index: number;
diff --git a/packages/ai/src/providers/google-shared.test.ts b/packages/ai/src/providers/google-shared.test.ts
index 3c9412d00f36..595380dd24f6 100644
--- a/packages/ai/src/providers/google-shared.test.ts
+++ b/packages/ai/src/providers/google-shared.test.ts
@@ -8,6 +8,7 @@ import {
   type Part,
 } from "@google/genai";
 import { describe, expect, it, vi } from "vitest";
+import { withProviderAcceptanceObserver } from "../transports/transport-stream-shared.js";
 import type { Model } from "../types.js";
 import { AssistantMessageEventStream } from "../utils/event-stream.js";
 import { SYSTEM_PROMPT_CACHE_BOUNDARY } from "../utils/system-prompt-cache-boundary.js";
@@ -590,6 +591,45 @@ describe("consumeGoogleGenerateContentStream", () => {
 });
 
 describe("runGoogleGenerateContentLifecycle", () => {
+  it("reports SDK stream acceptance without fabricated HTTP metadata", async () => {
+    const acceptanceObserver = vi.fn();
+    const options = withProviderAcceptanceObserver({}, acceptanceObserver);
+
+    const { result } = await runGoogleFixture(
+      [googleResponse({ parts: [{ text: "ok" }], finishReason: FinishReason.STOP })],
+      { options },
+    );
+
+    expect(result.stopReason).toBe("stop");
+    expect(acceptanceObserver).toHaveBeenCalledWith({ kind: "provider_stream_opened" });
+  });
+
+  it("closes an unread SDK stream without waiting when acceptance fails", async () => {
+    const close = vi.fn(() => new Promise<IteratorResult<GenerateContentResponse>>(() => {}));
+    const googleStream = {
+      next: vi.fn(),
+      return: close,
+      throw: vi.fn(),
+      [Symbol.asyncIterator]() {
+        return this;
+      },
+    } as unknown as AsyncGenerator<GenerateContentResponse>;
+
+    const options = withProviderAcceptanceObserver({}, () => {
+      throw new Error("acceptance observer failed");
+    });
+    const { result } = await runGoogleFixture([], {
+      options,
+      generateContentStream: async () => googleStream,
+    });
+
+    expect(result).toMatchObject({
+      stopReason: "error",
+      errorMessage: "acceptance observer failed",
+    });
+    expect(close).toHaveBeenCalledOnce();
+  });
+
   it.each(["google-generative-ai", "google-vertex"] as const)(
     "rejects an unfinished %s stream instead of silently completing partial output",
     async (api) => {
diff --git a/packages/ai/src/providers/google-shared.ts b/packages/ai/src/providers/google-shared.ts
index b8df401bc97e..5cda66ae63f7 100644
--- a/packages/ai/src/providers/google-shared.ts
+++ b/packages/ai/src/providers/google-shared.ts
@@ -19,6 +19,7 @@ import { googleFlashSupportsMinimalThinking } from "../transports/google-thinkin
 import {
   assignTransportErrorDetails,
   coerceTransportToolCallArguments,
+  notifyProviderStreamOpened,
   transportAbortError,
 } from "../transports/transport-stream-shared.js";
 import type {
@@ -436,8 +437,15 @@ export async function runGoogleGenerateContentLifecycle<T extends GoogleApiType>
       requestParams = nextParams as GenerateContentParameters;
     }
     const googleStream = await client.models.generateContentStream(requestParams);
+    const googleIterator = googleStream[Symbol.asyncIterator]();
+    await notifyProviderStreamOpened({
+      options,
+      cancelStream: async () => {
+        await googleIterator.return?.();
+      },
+    });
     await consumeGoogleGenerateContentStream({
-      chunks: googleStream,
+      chunks: { [Symbol.asyncIterator]: () => googleIterator },
       model,
       output,
       stream,
diff --git a/packages/ai/src/providers/mistral-http-client.contract.test.ts b/packages/ai/src/providers/mistral-http-client.contract.test.ts
new file mode 100644
index 000000000000..7057067d9a7c
--- /dev/null
+++ b/packages/ai/src/providers/mistral-http-client.contract.test.ts
@@ -0,0 +1,29 @@
+import { HTTPClient, Mistral } from "@mistralai/mistralai";
+import { describe, expect, it, vi } from "vitest";
+
+describe("Mistral HTTPClient contract", () => {
+  it("routes chat.stream responses through the injected HTTPClient hooks", async () => {
+    const response = new Response("data: [DONE]\n\n", {
+      status: 200,
+      headers: { "content-type": "text/event-stream" },
+    });
+    const fetcher = vi.fn(async () => response);
+    const onResponse = vi.fn();
+    const httpClient = new HTTPClient({ fetcher });
+    httpClient.addHook("response", onResponse);
+    const mistral = new Mistral({
+      apiKey: "test-key",
+      serverURL: "https://mistral.invalid",
+      httpClient,
+    });
+
+    const stream = await mistral.chat.stream({
+      model: "mistral-test",
+      messages: [{ role: "user", content: "hello" }],
+    });
+
+    expect(fetcher).toHaveBeenCalledOnce();
+    expect(onResponse).toHaveBeenCalledWith(response, expect.any(Request));
+    await stream.cancel("test complete");
+  });
+});
diff --git a/packages/ai/src/providers/mistral.test.ts b/packages/ai/src/providers/mistral.test.ts
index c34a47b331bb..913787507531 100644
--- a/packages/ai/src/providers/mistral.test.ts
+++ b/packages/ai/src/providers/mistral.test.ts
@@ -1,6 +1,7 @@
 import { toolCallFromJSON, type ToolCall } from "@mistralai/mistralai/models/components";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { configureAiTransportHost } from "../host.js";
+import { withProviderAcceptanceObserver } from "../transports/transport-stream-shared.js";
 import type { Context, Model } from "../types.js";
 import { SYSTEM_PROMPT_CACHE_BOUNDARY } from "../utils/system-prompt-cache-boundary.js";
 
@@ -9,6 +10,7 @@ const mistralMockState = vi.hoisted(() => ({
   payloads: [] as unknown[],
   requestOptions: [] as unknown[],
   randomUUIDs: [] as string[],
+  requestThroughHttpClient: false,
   streamError: new Error("stop before network") as unknown,
   streamResult: undefined as unknown,
 }));
@@ -27,7 +29,10 @@ vi.mock("@mistralai/mistralai", async () => {
   return {
     ...actual,
     Mistral: class MockMistral {
+      private readonly config: unknown;
+
       constructor(config: unknown) {
+        this.config = config;
         mistralMockState.configs.push(config);
       }
 
@@ -35,6 +40,19 @@ vi.mock("@mistralai/mistralai", async () => {
         stream: vi.fn(async (payload: unknown, requestOptions: unknown) => {
           mistralMockState.payloads.push(payload);
           mistralMockState.requestOptions.push(requestOptions);
+          if (mistralMockState.requestThroughHttpClient) {
+            const httpClient = (
+              this.config as {
+                httpClient?: { request(request: Request): Promise<Response> };
+              }
+            ).httpClient;
+            const response = await httpClient?.request(new Request("https://api.mistral.ai/chat"));
+            if (response && !response.ok) {
+              throw Object.assign(new Error(`Mistral HTTP ${response.status}`), {
+                statusCode: response.status,
+              });
+            }
+          }
           if (mistralMockState.streamResult !== undefined) {
             return mistralMockState.streamResult;
           }
@@ -219,6 +237,7 @@ describe("Mistral provider", () => {
     mistralMockState.payloads = [];
     mistralMockState.requestOptions = [];
     mistralMockState.randomUUIDs = [];
+    mistralMockState.requestThroughHttpClient = false;
     mistralMockState.streamError = new Error("stop before network");
     mistralMockState.streamResult = undefined;
   });
@@ -227,6 +246,125 @@ describe("Mistral provider", () => {
     configureAiTransportHost({});
   });
 
+  it("reports the real HTTP response captured by the Mistral HTTPClient hook", async () => {
+    mistralMockState.requestThroughHttpClient = true;
+    mistralMockState.streamResult = {
+      async *[Symbol.asyncIterator]() {
+        yield {
+          data: {
+            id: "resp-http-ack",
+            model: "mistral-large-latest",
+            choices: [{ finishReason: "stop", delta: { content: "ok" } }],
+          },
+        };
+      },
+    };
+    const hostFetch = vi.fn<typeof fetch>(
+      async () =>
+        new Response("stream", {
+          status: 200,
+          headers: {
+            "content-type": "text/event-stream",
+            "x-mistral-request-id": "req-1",
+          },
+        }),
+    );
+    configureAiTransportHost({ buildModelFetch: () => hostFetch });
+    const acceptanceObserver = vi.fn();
+    const onResponse = vi.fn();
+    const options = withProviderAcceptanceObserver({ onResponse }, acceptanceObserver);
+
+    const result = await runSimpleMistralFixture(context, options);
+
+    expect(result.stopReason).toBe("stop");
+    expect(acceptanceObserver).toHaveBeenCalledWith({
+      kind: "http_response",
+      status: 200,
+      headers: expect.objectContaining({
+        "content-type": "text/event-stream",
+        "x-mistral-request-id": "req-1",
+      }),
+    });
+    expect(onResponse).toHaveBeenCalledWith(
+      {
+        status: 200,
+        headers: expect.objectContaining({ "x-mistral-request-id": "req-1" }),
+      },
+      expect.objectContaining({ provider: "mistral" }),
+    );
+    expect(hostFetch).toHaveBeenCalledOnce();
+  });
+
+  it("cancels an unread Mistral stream when acceptance observation fails", async () => {
+    mistralMockState.requestThroughHttpClient = true;
+    const cancel = vi.fn(async () => undefined);
+    mistralMockState.streamResult = {
+      cancel,
+      async *[Symbol.asyncIterator]() {
+        yield {
+          data: {
+            id: "resp-http-ack",
+            model: "mistral-large-latest",
+            choices: [{ finishReason: "stop", delta: { content: "ok" } }],
+          },
+        };
+      },
+    };
+    configureAiTransportHost({
+      buildModelFetch: () => async () => new Response("stream", { status: 200 }),
+    });
+    const hookError = new Error("acceptance observer failed");
+    const options = withProviderAcceptanceObserver({}, () => {
+      throw hookError;
+    });
+
+    const result = await runSimpleMistralFixture(context, options);
+
+    expect(result).toMatchObject({
+      stopReason: "error",
+      errorMessage: "acceptance observer failed",
+    });
+    expect(cancel).toHaveBeenCalledWith(hookError);
+  });
+
+  it("reports a rejected HTTP response without marking it accepted", async () => {
+    mistralMockState.requestThroughHttpClient = true;
+    const hostFetch = vi.fn<typeof fetch>(
+      async () =>
+        new Response("rate limited", {
+          status: 429,
+          headers: { "x-mistral-request-id": "req-rejected" },
+        }),
+    );
+    configureAiTransportHost({ buildModelFetch: () => hostFetch });
+    const acceptanceObserver = vi.fn();
+    const onResponse = vi.fn();
+    const options = withProviderAcceptanceObserver({ onResponse }, acceptanceObserver);
+
+    const result = await runSimpleMistralFixture(context, options);
+
+    expect(result.stopReason).toBe("error");
+    expect(acceptanceObserver).not.toHaveBeenCalled();
+    expect(onResponse).toHaveBeenCalledWith(
+      {
+        status: 429,
+        headers: expect.objectContaining({ "x-mistral-request-id": "req-rejected" }),
+      },
+      expect.objectContaining({ provider: "mistral" }),
+    );
+    expect(hostFetch).toHaveBeenCalledOnce();
+  });
+
+  it("does not report acceptance when SDK stream setup fails", async () => {
+    const acceptanceObserver = vi.fn();
+    const options = withProviderAcceptanceObserver({}, acceptanceObserver);
+
+    const result = await runSimpleMistralFixture(context, options);
+
+    expect(result.stopReason).toBe("error");
+    expect(acceptanceObserver).not.toHaveBeenCalled();
+  });
+
   it("forwards simple stop sequences to Mistral stop", async () => {
     const result = await runSimpleMistralFixture(context, {
       stop: ["STOP"],
diff --git a/packages/ai/src/providers/mistral.ts b/packages/ai/src/providers/mistral.ts
index 88cafcf3f4f5..97c1ca0572f2 100644
--- a/packages/ai/src/providers/mistral.ts
+++ b/packages/ai/src/providers/mistral.ts
@@ -14,6 +14,7 @@ import { calculateCost, clampThinkingLevel } from "../model-utils.js";
 import { transformProviderMessages as transformMessages } from "../provider-transcript-transform.js";
 import {
   finalizeTerminalToolCallArguments,
+  notifyProviderHttpResponse,
   transportAbortError,
 } from "../transports/transport-stream-shared.js";
 import type {
@@ -141,24 +142,28 @@ export const streamMistral: StreamFunction<"mistral-conversations", MistralOptio
         throw new Error(`No API key for provider: ${model.provider}`);
       }
 
+      const boundedFetcher = createBoundedMistralFetcher(
+        MISTRAL_STREAM_BODY_MAX_BYTES,
+        getAiTransportHost().buildModelFetch(model) ?? fetch,
+      );
+      let mistralResponse: Response | undefined;
+      let reportedResponse: Response | undefined;
+      const httpClient = new HTTPClient({ fetcher: boundedFetcher });
+      httpClient.addHook("response", async (response) => {
+        mistralResponse = response;
+        if (!response.ok) {
+          await notifyProviderHttpResponse({ options, response, model });
+          reportedResponse = response;
+        }
+      });
       // Intentionally per-request: avoids shared SDK mutable state across concurrent consumers.
       const mistral = new Mistral({
         apiKey,
         serverURL: model.baseUrl,
         // Bound the streamed Mistral response body at 16 MiB so a hostile or
-        // malfunctioning endpoint cannot exhaust memory. The fetcher is
-        // injected via the SDK's `HTTPClient` (see
-        // `@mistralai/mistralai/lib/sdks.ts` `ClientSDK` constructor: when
-        // `httpClient` is passed, `ClientSDK.#httpClient` is set from it and
-        // every `chat.stream` / `complete` call routes through
-        // `HTTPClient.request` → `this.fetcher(req)`).
-        // Mistral accepts HTTPClient.fetcher, so compose guarded egress with the byte cap.
-        httpClient: new HTTPClient({
-          fetcher: createBoundedMistralFetcher(
-            MISTRAL_STREAM_BODY_MAX_BYTES,
-            getAiTransportHost().buildModelFetch(model) ?? fetch,
-          ),
-        }),
+        // malfunctioning endpoint cannot exhaust memory. The HTTPClient is the
+        // SDK's public fetch and response-hook boundary for every chat.stream attempt.
+        httpClient,
       });
 
       const normalizeMistralToolCallId = createMistralToolCallIdNormalizer();
@@ -181,6 +186,14 @@ export const streamMistral: StreamFunction<"mistral-conversations", MistralOptio
         headers,
         signal: options?.signal,
       });
+      if (mistralResponse && mistralResponse !== reportedResponse) {
+        await notifyProviderHttpResponse({
+          options,
+          response: mistralResponse,
+          model,
+          cancelStream: (reason) => mistralStream.cancel(reason),
+        });
+      }
       stream.push({ type: "start", partial: output });
       await consumeChatStream(model, output, stream, mistralStream);
 
diff --git a/packages/ai/src/providers/openai-chatgpt-responses-streaming.test.ts b/packages/ai/src/providers/openai-chatgpt-responses-streaming.test.ts
index 4ad10c424edf..79deb31e0728 100644
--- a/packages/ai/src/providers/openai-chatgpt-responses-streaming.test.ts
+++ b/packages/ai/src/providers/openai-chatgpt-responses-streaming.test.ts
@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { configureAiTransportHost } from "../host.js";
+import { withProviderAcceptanceObserver } from "../transports/transport-stream-shared.js";
 import type { Context, Model } from "../types.js";
 import {
   closeOpenAICodexWebSocketSessions,
@@ -151,6 +152,60 @@ describe("OpenAI ChatGPT Responses inference streaming", () => {
     });
   });
 
+  it("reports acceptance before the default WebSocket stream starts", async () => {
+    class AcceptedWebSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(): void {
+        queueMicrotask(() => {
+          this.dispatchEvent(
+            Object.assign(new Event("message"), {
+              data: JSON.stringify({
+                type: "response.completed",
+                response: {
+                  id: "resp_ws_accepted",
+                  status: "completed",
+                  output: [],
+                  usage: { input_tokens: 5, output_tokens: 3, total_tokens: 8 },
+                },
+              }),
+            }),
+          );
+        });
+      }
+
+      close(): void {}
+    }
+
+    const order: string[] = [];
+    const acceptanceObserver = vi.fn(() => {
+      order.push("accepted");
+    });
+    const fetchMock = vi.fn();
+    vi.stubGlobal("WebSocket", AcceptedWebSocket);
+    vi.stubGlobal("fetch", fetchMock);
+    const options = withProviderAcceptanceObserver(
+      {
+        apiKey: createJwt({
+          "https://api.openai.com/auth": { chatgpt_account_id: "acct-1" },
+        }),
+      },
+      acceptanceObserver,
+    );
+
+    const stream = streamOpenAICodexResponses(model, context, options);
+    for await (const event of stream) {
+      order.push(event.type);
+    }
+
+    expect(order).toEqual(["accepted", "start", "done"]);
+    expect(acceptanceObserver).toHaveBeenCalledWith({ kind: "provider_stream_opened" });
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("emits an error for a content-filtered incomplete WebSocket turn", async () => {
     class ContentFilteredWebSocket extends EventTarget {
       constructor() {
diff --git a/packages/ai/src/providers/openai-chatgpt-responses.encrypted-retry.test.ts b/packages/ai/src/providers/openai-chatgpt-responses.encrypted-retry.test.ts
index 0a95003e94b0..29aee21db831 100644
--- a/packages/ai/src/providers/openai-chatgpt-responses.encrypted-retry.test.ts
+++ b/packages/ai/src/providers/openai-chatgpt-responses.encrypted-retry.test.ts
@@ -7,6 +7,7 @@ import {
   captureOpenAIResponsesCompaction,
 } from "../transports/openai-responses-compaction-replay.js";
 import { OPENAI_RESPONSES_REASONING_REPLAY_META_KEY } from "../transports/openai-responses-contracts.js";
+import { withProviderAcceptanceObserver } from "../transports/transport-stream-shared.js";
 import type { AssistantMessage, Context, Model } from "../types.js";
 import {
   closeOpenAICodexWebSocketSessions,
@@ -544,6 +545,47 @@ describe("ChatGPT Responses encrypted replay recovery", () => {
     expect(onCompactionRejected).toHaveBeenCalledOnce();
   });
 
+  it("WebSocket commits stripped compaction before acceptance observation fails", async () => {
+    const context = createReplayContext("compaction");
+    const onCompactionRejected = vi.fn();
+    const observations: ResponsesPromptObservation[] = [];
+    const scripted = installScriptedWebSocket([
+      { events: [invalidEncryptedEvent()] },
+      { events: [completionEvent("resp_ws_hook_failure")] },
+    ]);
+    const baseOptions = createObservedOptions(
+      {
+        apiKey: createJwt(),
+        transport: "websocket" as const,
+        onCompactionRejected,
+        ...REPLAY_IDENTITY,
+      },
+      observations,
+    );
+    const options = withProviderAcceptanceObserver(baseOptions, () => {
+      if (scripted.requests.length >= 2) {
+        throw new Error("acceptance observer failed");
+      }
+    });
+
+    const result = await streamOpenAICodexResponses(model, context, options).result();
+
+    expect(result).toMatchObject({
+      stopReason: "error",
+      errorMessage: "acceptance observer failed",
+      providerReplay: { type: "openai-responses-compaction-suppression" },
+    });
+    expect(scripted.requests).toHaveLength(2);
+    expect(hasInputType(requireItem(scripted.requests, 0), "compaction")).toBe(true);
+    expect(hasInputType(requireItem(scripted.requests, 1), "compaction")).toBe(false);
+    expect(observations.map((entry) => entry.payloadVariant)).toEqual([
+      "initial",
+      "compaction-stripped",
+    ]);
+    expect(onCompactionRejected).toHaveBeenCalledOnce();
+    expect(scripted.sockets[1]?.closed).toBe(true);
+  });
+
   it("WebSocket preserves compaction when reasoning-stripped recovery succeeds", async () => {
     const context = createReplayContext("mixed");
     const observations: ResponsesPromptObservation[] = [];
diff --git a/packages/ai/src/providers/openai-chatgpt-responses.retry.test.ts b/packages/ai/src/providers/openai-chatgpt-responses.retry.test.ts
index 5a3256e4ff25..62ce41a604f8 100644
--- a/packages/ai/src/providers/openai-chatgpt-responses.retry.test.ts
+++ b/packages/ai/src/providers/openai-chatgpt-responses.retry.test.ts
@@ -2,6 +2,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { configureAiTransportHost } from "../host.js";
 import { responsesPromptObserver, type ResponsesPromptObservation } from "../internal/openai.js";
+import { withProviderAcceptanceObserver } from "../transports/transport-stream-shared.js";
 import type { Context, Model } from "../types.js";
 import {
   closeOpenAICodexWebSocketSessions,
@@ -92,10 +93,16 @@ describe("streamOpenAICodexResponses retry classification", () => {
       return 0 as unknown as ReturnType<typeof setTimeout>;
     });
 
-    const options = {
-      apiKey: jwt,
-      transport: "sse" as const,
-    };
+    const acceptanceObserver = vi.fn();
+    const onResponse = vi.fn();
+    const options = withProviderAcceptanceObserver(
+      {
+        apiKey: jwt,
+        transport: "sse" as const,
+        onResponse,
+      },
+      acceptanceObserver,
+    );
     responsesPromptObserver.set(options, (observation) => observations.push(observation));
 
     const result = await streamOpenAICodexResponses(
@@ -106,6 +113,8 @@ describe("streamOpenAICodexResponses retry classification", () => {
 
     expect(result.stopReason).toBe("error");
     expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(acceptanceObserver).not.toHaveBeenCalled();
+    expect(onResponse.mock.calls.map(([response]) => response.status)).toEqual([503, 401]);
     expect(observations).toHaveLength(2);
     expect(observations.every((entry) => entry.egress === "native-codex-sse")).toBe(true);
     expect(observations.every((entry) => entry.payloadVariant === "initial")).toBe(true);
diff --git a/packages/ai/src/providers/openai-chatgpt-responses.ts b/packages/ai/src/providers/openai-chatgpt-responses.ts
index 81c7ab1a5ddd..593efca5569c 100644
--- a/packages/ai/src/providers/openai-chatgpt-responses.ts
+++ b/packages/ai/src/providers/openai-chatgpt-responses.ts
@@ -33,8 +33,12 @@ import {
   type ResponsesEncryptedContentAttempt,
 } from "../transports/openai-responses-replay-internal.js";
 import { processResponsesStream } from "../transports/openai-responses-stream-internal.js";
-import { createOpenAIResponseHook } from "../transports/openai-transport-shared.js";
 import {
+  createOpenAIProviderAcceptanceHook,
+  createOpenAIResponseHook,
+} from "../transports/openai-transport-shared.js";
+import {
+  notifyProviderStreamOpened,
   transportAbortError,
   withProviderResponseHook,
 } from "../transports/transport-stream-shared.js";
@@ -360,9 +364,11 @@ export const streamOpenAICodexResponses: StreamFunction<
               stream,
               model,
               () => {
-                commitSemanticAttempt(activeAttempt);
                 websocketStarted = true;
               },
+              () => {
+                commitSemanticAttempt(activeAttempt);
+              },
               requestOptions,
               firstEventAbort.abort,
               observePromptEgress,
@@ -582,7 +588,7 @@ export const streamOpenAICodexResponses: StreamFunction<
         stream: mapCodexEvents(parseOpenAIChatGptResponsesSse(response)),
         signal: firstEventAbort.signal,
         abort: firstEventAbort.abort,
-        hook: createOpenAIResponseHook(options?.onResponse, response, model),
+        hook: createOpenAIProviderAcceptanceHook(options, response, model),
         onReady: () => stream.push({ type: "start", partial: output }),
       });
       await processResponsesStream(hookedResponseStream, output, stream, model, {
@@ -1453,13 +1459,17 @@ async function* startWebSocketOutputOnFirstEvent(
   events: AsyncIterable<ResponseStreamEvent>,
   output: AssistantMessage,
   stream: AssistantMessageEventStream,
+  onFirstProviderEvent: () => void,
+  reportStreamOpened: () => Promise<void>,
   onStart: () => void,
 ): AsyncGenerator<ResponseStreamEvent> {
   let started = false;
   for await (const event of events) {
     if (!started) {
       started = true;
+      onFirstProviderEvent();
       onStart();
+      await reportStreamOpened();
       stream.push({ type: "start", partial: output });
     }
     yield event;
@@ -1473,6 +1483,7 @@ async function processWebSocketStream(
   output: AssistantMessage,
   stream: AssistantMessageEventStream,
   model: Model<"openai-chatgpt-responses">,
+  onFirstProviderEvent: () => void,
   onStart: () => void,
   options?: OpenAICodexResponsesOptions,
   abortFirstEventStream?: (reason: Error) => void,
@@ -1509,6 +1520,15 @@ async function processWebSocketStream(
         mapCodexEvents(parseWebSocket(socket, options?.signal)),
         output,
         stream,
+        onFirstProviderEvent,
+        () =>
+          notifyProviderStreamOpened({
+            options,
+            cancelStream: () => {
+              keepConnection = false;
+              closeWebSocketSilently(socket);
+            },
+          }),
         onStart,
       ),
       output,
diff --git a/packages/ai/src/providers/openai-completions.ts b/packages/ai/src/providers/openai-completions.ts
index e007e755fd36..20cab4f377ce 100644
--- a/packages/ai/src/providers/openai-completions.ts
+++ b/packages/ai/src/providers/openai-completions.ts
@@ -19,7 +19,7 @@ import {
 } from "../transports/openai-completions-compat.js";
 import { resolveOpenAIReasoningEffortMap } from "../transports/openai-reasoning-compat.js";
 import {
-  createOpenAIResponseHook,
+  createOpenAIProviderAcceptanceHook,
   isOpenAICompletionsThinkingEnabled,
   parseOpenAICompletionsUsage,
   readOpenAICompletionsContentDeltas,
@@ -184,7 +184,7 @@ export const streamOpenAICompletions: StreamFunction<
         stream: openaiStream,
         signal: firstEventAbort.signal,
         abort: firstEventAbort.abort,
-        hook: createOpenAIResponseHook(options?.onResponse, response, model),
+        hook: createOpenAIProviderAcceptanceHook(options, response, model),
         onReady: () => stream.push({ type: "start", partial: output }),
       });
 
diff --git a/packages/ai/src/providers/openai-responses-shared.ts b/packages/ai/src/providers/openai-responses-shared.ts
index a3cfdd65e4b7..3166ee133919 100644
--- a/packages/ai/src/providers/openai-responses-shared.ts
+++ b/packages/ai/src/providers/openai-responses-shared.ts
@@ -18,7 +18,7 @@ import {
   convertProviderResponsesMessages,
 } from "../transports/openai-responses-replay-internal.js";
 import { processResponsesStream } from "../transports/openai-responses-stream-internal.js";
-import { createOpenAIResponseHook } from "../transports/openai-transport-shared.js";
+import { createOpenAIProviderAcceptanceHook } from "../transports/openai-transport-shared.js";
 import {
   transportAbortError,
   withProviderResponseHook,
@@ -296,7 +296,7 @@ export async function runResponsesStreamLifecycle<TApi extends Api>(params: {
       stream: openaiStream,
       signal: firstEventAbort.signal,
       abort: firstEventAbort.abort,
-      hook: createOpenAIResponseHook(options?.onResponse, response, model),
+      hook: createOpenAIProviderAcceptanceHook(options, response, model),
       onReady: () => stream.push({ type: "start", partial: output }),
     });
 
diff --git a/packages/ai/src/providers/simple-options.ts b/packages/ai/src/providers/simple-options.ts
index e0ae64ac9a74..05c46389344d 100644
--- a/packages/ai/src/providers/simple-options.ts
+++ b/packages/ai/src/providers/simple-options.ts
@@ -1,3 +1,4 @@
+import { copyProviderAcceptanceObserver } from "../transports/transport-stream-shared.js";
 // Simple provider option helpers normalize lightweight provider configuration.
 import type {
   Model,
@@ -19,7 +20,7 @@ export function buildBaseOptions(
 ): StreamOptions & FirstEventStreamOptions {
   void model;
   const firstEventOptions = options as FirstEventStreamOptions | undefined;
-  return {
+  const baseOptions = {
     temperature: options?.temperature,
     maxTokens: options?.maxTokens,
     stop: options?.stop,
@@ -39,6 +40,7 @@ export function buildBaseOptions(
     maxRetryDelayMs: options?.maxRetryDelayMs,
     metadata: options?.metadata,
   };
+  return copyProviderAcceptanceObserver(options, baseOptions);
 }
 
 export function clampMaxTokensToModel(model: Model, requestedMaxTokens: number): number;
diff --git a/packages/ai/src/transports/anthropic-transport-stream.test.ts b/packages/ai/src/transports/anthropic-transport-stream.test.ts
index 1195e3610809..fc3d11cf8e59 100644
--- a/packages/ai/src/transports/anthropic-transport-stream.test.ts
+++ b/packages/ai/src/transports/anthropic-transport-stream.test.ts
@@ -12,6 +12,7 @@ import {
   type AiInlineContentBlock,
 } from "../host.js";
 import { createCompactionCapture } from "./anthropic-compaction-replay.js";
+import { withProviderAcceptanceObserver } from "./transport-stream-shared.js";
 
 const { buildGuardedModelFetchMock, guardedFetchMock } = vi.hoisted(() => ({
   buildGuardedModelFetchMock: vi.fn(),
@@ -73,7 +74,7 @@ let createAnthropicMessagesTransportStreamFn: typeof import("./anthropic-transpo
 type AnthropicMessagesModel = Model<"anthropic-messages">;
 type AnthropicStreamFn = ReturnType<typeof createAnthropicMessagesTransportStreamFn>;
 type AnthropicStreamContext = Parameters<AnthropicStreamFn>[1];
-type AnthropicStreamOptions = Parameters<AnthropicStreamFn>[2];
+type AnthropicStreamOptions = NonNullable<Parameters<AnthropicStreamFn>[2]>;
 type RequestTransportConfig = {
   proxy?: unknown;
   tls?: unknown;
@@ -1132,18 +1133,29 @@ describe("anthropic transport stream", () => {
       ),
     );
 
+    const acceptanceObserver = vi.fn();
+    const onResponse = vi.fn();
+    const options = withProviderAcceptanceObserver(
+      { apiKey: "test-api-key", onResponse } as AnthropicStreamOptions,
+      acceptanceObserver,
+    );
     const result = await runTransportStream(
       makeAnthropicTransportModel(),
       {
         messages: [{ role: "user", content: "hello" }],
       } as AnthropicStreamContext,
-      { apiKey: "test-api-key" } as AnthropicStreamOptions,
+      options,
     );
 
     expect(result.stopReason).toBe("error");
     expect(result.errorMessage).toBe(
       'HTTP 429: {"type":"error","error":{"type":"rate_limit_error","message":"Number of request tokens exceeded the per-minute rate limit."}}; Retry-After: 30 seconds',
     );
+    expect(acceptanceObserver).not.toHaveBeenCalled();
+    expect(onResponse).toHaveBeenCalledWith(
+      { status: 429, headers: { "content-type": "text/plain;charset=UTF-8", "retry-after": "30" } },
+      expect.objectContaining({ provider: "anthropic" }),
+    );
   });
 
   it("bounds streamed Anthropic error responses without content-length", async () => {
@@ -3940,6 +3952,36 @@ describe("anthropic transport stream", () => {
     expect(cancelReason).toBe(abortReason);
   });
 
+  it("cancels an unread SSE body when acceptance observation fails", async () => {
+    let cancelCalled = false;
+    guardedFetchMock.mockResolvedValueOnce(
+      createOpenRawSseResponse({
+        body: "",
+        onCancel: () => {
+          cancelCalled = true;
+        },
+      }),
+    );
+    const options = withProviderAcceptanceObserver(
+      { apiKey: "sk-ant-api" } as AnthropicStreamOptions,
+      () => {
+        throw new Error("acceptance observer failed");
+      },
+    );
+
+    const result = await runTransportStream(
+      makeAnthropicTransportModel(),
+      { messages: [{ role: "user", content: "hello" }] } as AnthropicStreamContext,
+      options,
+    );
+
+    expect(result).toMatchObject({
+      stopReason: "error",
+      errorMessage: "acceptance observer failed",
+    });
+    await vi.waitFor(() => expect(cancelCalled).toBe(true));
+  });
+
   it("cancels open SSE bodies when Anthropic stream consumers throw", async () => {
     let cancelCalled = false;
     guardedFetchMock.mockResolvedValueOnce(
@@ -4479,10 +4521,16 @@ describe("anthropic transport stream", () => {
       ]),
     );
     const streamFn = createAnthropicMessagesTransportStreamFn();
+    const acceptanceObserver = vi.fn();
+    const onResponse = vi.fn();
+    const options = withProviderAcceptanceObserver(
+      { apiKey: "sk-ant-api", onResponse } as AnthropicStreamOptions,
+      acceptanceObserver,
+    );
     const stream = streamFn(
       makeAnthropicTransportModel(),
       { messages: [{ role: "user", content: "hi" }] } as AnthropicStreamContext,
-      { apiKey: "sk-ant-api" } as AnthropicStreamOptions,
+      options,
     );
 
     const eventTypes: string[] = [];
@@ -4493,6 +4541,15 @@ describe("anthropic transport stream", () => {
     const startIndex = eventTypes.indexOf("start");
     expect(startIndex).toBeGreaterThanOrEqual(0);
     expect(eventTypes.slice(0, startIndex).some((t) => t === "error")).toBe(false);
+    expect(acceptanceObserver).toHaveBeenCalledWith({
+      kind: "http_response",
+      status: 200,
+      headers: { "content-type": "text/event-stream" },
+    });
+    expect(onResponse).toHaveBeenCalledWith(
+      { status: 200, headers: { "content-type": "text/event-stream" } },
+      expect.objectContaining({ provider: "anthropic" }),
+    );
   });
 
   it("emits error without a preceding start event when SSE error arrives before message_start", async () => {
@@ -4507,10 +4564,16 @@ describe("anthropic transport stream", () => {
       ),
     );
     const streamFn = createAnthropicMessagesTransportStreamFn();
+    const acceptanceObserver = vi.fn();
+    const onResponse = vi.fn();
+    const options = withProviderAcceptanceObserver(
+      { apiKey: "sk-ant-api", onResponse } as AnthropicStreamOptions,
+      acceptanceObserver,
+    );
     const stream = streamFn(
       makeAnthropicTransportModel(),
       { messages: [{ role: "user", content: "hi" }] } as AnthropicStreamContext,
-      { apiKey: "sk-ant-api" } as AnthropicStreamOptions,
+      options,
     );
 
     const eventTypes: string[] = [];
@@ -4522,6 +4585,15 @@ describe("anthropic transport stream", () => {
     // surfaces the SSE error as an explicit "error" event or silently ends the
     // stream (a timing artefact of synchronous mock SSE delivery).
     expect(eventTypes).not.toContain("start");
+    expect(acceptanceObserver).toHaveBeenCalledWith({
+      kind: "http_response",
+      status: 200,
+      headers: { "content-type": "text/event-stream" },
+    });
+    expect(onResponse).toHaveBeenCalledWith(
+      { status: 200, headers: { "content-type": "text/event-stream" } },
+      expect.objectContaining({ provider: "anthropic" }),
+    );
   });
 });
 /* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */
diff --git a/packages/ai/src/transports/anthropic-transport-stream.ts b/packages/ai/src/transports/anthropic-transport-stream.ts
index 9b939d1a384a..8aa3387aa246 100644
--- a/packages/ai/src/transports/anthropic-transport-stream.ts
+++ b/packages/ai/src/transports/anthropic-transport-stream.ts
@@ -102,12 +102,14 @@ import {
 import { parseJsonObjectPreservingUnsafeIntegers } from "./json-unsafe-integers.js";
 import {
   coerceTransportToolCallArguments,
+  copyProviderAcceptanceObserver,
   createEmptyTransportUsage,
   createWritableTransportEventStream,
   failTransportStream,
   finalizeTerminalToolCallArguments,
   finalizeTransportStream,
   mergeTransportHeaders,
+  notifyProviderHttpResponse,
   sanitizeNonEmptyTransportPayloadText,
   sanitizeTransportPayloadText,
   transportAbortError,
@@ -144,7 +146,10 @@ type AnthropicMessagesClient = {
     stream(
       params: Record<string, unknown>,
       options?: { signal?: AbortSignal },
-    ): AsyncIterable<Record<string, unknown>>;
+    ): Promise<{
+      response: Response;
+      stream: AsyncIterable<Record<string, unknown>> | Iterable<Record<string, unknown>>;
+    }>;
   };
 };
 
@@ -742,7 +747,7 @@ function createAnthropicMessagesClient(params: {
   const url = resolveAnthropicMessagesUrl(params.baseURL);
   return {
     messages: {
-      async *stream(body: Record<string, unknown>, options?: { signal?: AbortSignal }) {
+      async stream(body: Record<string, unknown>, options?: { signal?: AbortSignal }) {
         const headers = mergeTransportHeaders(
           {
             "content-type": "application/json",
@@ -758,14 +763,10 @@ function createAnthropicMessagesClient(params: {
           body: JSON.stringify(body),
           signal: options?.signal,
         });
-        if (!response.ok) {
-          const detail = await readAnthropicMessagesErrorBodySnippet(response);
-          throw new Error(formatAnthropicMessagesHttpError(response, detail));
-        }
-        if (!response.body) {
-          return;
-        }
-        yield* parseAnthropicSseBody(response.body, options?.signal);
+        return {
+          response,
+          stream: response.body ? parseAnthropicSseBody(response.body, options?.signal) : [],
+        };
       },
     },
   };
@@ -1085,7 +1086,7 @@ function resolveAnthropicTransportOptions(
   const mandatoryAdaptiveThinking = requiresClaudeAdaptiveThinking(model);
   const reasoning =
     options?.reasoning === "off" && mandatoryAdaptiveThinking ? "low" : options?.reasoning;
-  const resolved: AnthropicTransportOptions = {
+  const resolved: AnthropicTransportOptions = copyProviderAcceptanceObserver(options, {
     temperature: options?.temperature,
     stop: options?.stop,
     maxTokens: baseMaxTokens,
@@ -1095,6 +1096,7 @@ function resolveAnthropicTransportOptions(
     sessionId: options?.sessionId,
     headers: options?.headers,
     onPayload: options?.onPayload,
+    onResponse: options?.onResponse,
     maxRetryDelayMs: options?.maxRetryDelayMs,
     metadata: options?.metadata,
     interleavedThinking: options?.interleavedThinking,
@@ -1103,7 +1105,7 @@ function resolveAnthropicTransportOptions(
     reasoning,
     ...(options?.anthropicServerCompaction === true ? { anthropicServerCompaction: true } : {}),
     ...(options?.authProfileId ? { authProfileId: options.authProfileId } : {}),
-  };
+  });
   if (reasoning === "off") {
     resolved.thinkingEnabled = false;
     return resolved;
@@ -1192,10 +1194,15 @@ export function createAnthropicMessagesTransportStreamFn(): StreamFn {
           params = nextParams as Record<string, unknown>;
         }
         applyClaudeRequestContract(params, model);
-        const anthropicStream = client.messages.stream(
+        const { response, stream: anthropicStream } = await client.messages.stream(
           { ...params, stream: true },
           transportOptions.signal ? { signal: transportOptions.signal } : undefined,
         );
+        await notifyProviderHttpResponse({ options: transportOptions, response, model });
+        if (!response.ok) {
+          const detail = await readAnthropicMessagesErrorBodySnippet(response);
+          throw new Error(formatAnthropicMessagesHttpError(response, detail));
+        }
         const blocks = output.content;
         const blockIndexes = new Map<number, number>();
         const sealedToolCalls: Array<{
diff --git a/packages/ai/src/transports/openai-completions-transport.response-hook.test.ts b/packages/ai/src/transports/openai-completions-transport.response-hook.test.ts
index a5a4c30e9189..5f06b6f410e8 100644
--- a/packages/ai/src/transports/openai-completions-transport.response-hook.test.ts
+++ b/packages/ai/src/transports/openai-completions-transport.response-hook.test.ts
@@ -3,6 +3,10 @@ import { configureAiTransportHost, getAiTransportHost } from "../host.js";
 import { streamOpenAICompletions } from "../providers/openai-completions.js";
 import type { AssistantMessageEventStreamLike, Context, Model, StreamOptions } from "../types.js";
 import { createOpenAICompletionsTransportStreamFn } from "./openai-completions-transport.js";
+import {
+  withProviderAcceptanceObserver,
+  type ProviderAcceptance,
+} from "./transport-stream-shared.js";
 
 const model = {
   id: "gpt-5.5",
@@ -116,12 +120,19 @@ describe.each([
     const hookCompleted = new Promise<void>((resolve) => {
       continueHook = resolve;
     });
+    const acceptanceObserver = vi.fn((acceptance: ProviderAcceptance) => {
+      order.push(`accepted:${acceptance.kind}`);
+    });
     const onResponse = vi.fn<NonNullable<StreamOptions["onResponse"]>>(async () => {
       order.push("hook:start");
       await hookCompleted;
       order.push("hook:end");
     });
-    const stream = createStream(model, context, { apiKey: "fixture-token", onResponse });
+    const options = withProviderAcceptanceObserver(
+      { apiKey: "fixture-token", onResponse },
+      acceptanceObserver,
+    );
+    const stream = createStream(model, context, options);
     const consume = (async () => {
       for await (const event of stream) {
         order.push(event.type);
@@ -129,7 +140,16 @@ describe.each([
     })();
 
     await vi.waitFor(() => expect(onResponse).toHaveBeenCalledOnce());
-    expect(order).toEqual(["hook:start"]);
+    expect(order).toEqual(["accepted:http_response", "hook:start"]);
+    expect(acceptanceObserver).toHaveBeenCalledWith({
+      kind: "http_response",
+      status: 202,
+      headers: {
+        "content-type": "text/event-stream",
+        "x-ratelimit-remaining-requests": "42",
+        "x-request-id": "req_observable",
+      },
+    });
     expect(onResponse).toHaveBeenCalledWith(
       {
         status: 202,
@@ -145,7 +165,12 @@ describe.each([
     continueHook();
     await consume;
     expect((await stream.result()).stopReason).toBe("stop");
-    expect(order.slice(0, 3)).toEqual(["hook:start", "hook:end", "start"]);
+    expect(order.slice(0, 4)).toEqual([
+      "accepted:http_response",
+      "hook:start",
+      "hook:end",
+      "start",
+    ]);
   });
 
   it.each(["throw", "reject"] as const)(
@@ -177,6 +202,34 @@ describe.each([
     },
   );
 
+  it("preserves an acceptance observer failure and closes the unread request", async () => {
+    const lifecycle = installResponse();
+    const hookError = new Error("provider acceptance observer failed");
+    const acceptanceObserver = vi.fn(() => {
+      throw hookError;
+    });
+    const onResponse = vi.fn();
+    const options = withProviderAcceptanceObserver(
+      { apiKey: "fixture-token", onResponse },
+      acceptanceObserver,
+    );
+    const stream = createStream(model, context, options);
+    const eventTypes: string[] = [];
+
+    for await (const event of stream) {
+      eventTypes.push(event.type);
+    }
+
+    expect(await stream.result()).toMatchObject({
+      stopReason: "error",
+      errorMessage: "provider acceptance observer failed",
+    });
+    expect(acceptanceObserver).toHaveBeenCalledOnce();
+    expect(onResponse).not.toHaveBeenCalled();
+    expect(eventTypes).toEqual(["error"]);
+    expect(lifecycle.requestAborted).toHaveBeenCalledOnce();
+  });
+
   it("applies the first-event timeout while the hook is pending", async () => {
     const lifecycle = installResponse();
     const onFirstEventTimeout = vi.fn();
diff --git a/packages/ai/src/transports/openai-completions-transport.ts b/packages/ai/src/transports/openai-completions-transport.ts
index cd50c705b7b2..f410d36d26ea 100644
--- a/packages/ai/src/transports/openai-completions-transport.ts
+++ b/packages/ai/src/transports/openai-completions-transport.ts
@@ -27,7 +27,7 @@ import {
   resolveCodeModeResponsesVisibleToolNames,
 } from "./openai-transport-params.js";
 import {
-  createOpenAIResponseHook,
+  createOpenAIProviderAcceptanceHook,
   type MutableAssistantOutput,
   type OpenAIModeModel,
 } from "./openai-transport-shared.js";
@@ -271,7 +271,7 @@ export function createOpenAICompletionsTransportStreamFn(): StreamFn {
           stream: responseStream,
           signal: firstEventAbort.signal,
           abort: firstEventAbort.abort,
-          hook: createOpenAIResponseHook(options?.onResponse, response, model),
+          hook: createOpenAIProviderAcceptanceHook(options, response, model),
           onReady: () => stream.push({ type: "start", partial: output }),
         });
         await processCompletionsStream(hookedResponseStream, output, model, stream, {
diff --git a/packages/ai/src/transports/openai-responses-client.ts b/packages/ai/src/transports/openai-responses-client.ts
index fa9e6ce94521..988a5910010e 100644
--- a/packages/ai/src/transports/openai-responses-client.ts
+++ b/packages/ai/src/transports/openai-responses-client.ts
@@ -70,13 +70,14 @@ import {
   isOpenAICodexResponsesModel,
   resolveCodeModeResponsesVisibleToolNames,
 } from "./openai-transport-params.js";
-import { createOpenAIResponseHook, log } from "./openai-transport-shared.js";
+import { createOpenAIProviderAcceptanceHook, log } from "./openai-transport-shared.js";
 import { sanitizeResponsesImagePayload } from "./responses-image-payload-sanitizer.js";
 import {
   createWritableTransportEventStream,
   failTransportStream,
   finalizeTransportStream,
   mergeTransportMetadata,
+  notifyProviderStreamOpened,
   transportAbortError,
   withProviderResponseHook,
 } from "./transport-stream-shared.js";
@@ -448,7 +449,7 @@ function createResponsesTransportExecutor(config: ResponsesTransportExecutorOpti
             stream: observeResponsesStream(rawResponseStream, model, requestStartedAt),
             signal: firstEvent.signal,
             abort: firstEvent.abort,
-            hook: createOpenAIResponseHook(options?.onResponse, response, model),
+            hook: createOpenAIProviderAcceptanceHook(options, response, model),
             onReady: () => {
               emitModelTransportDebug(
                 log,
@@ -503,8 +504,16 @@ function createResponsesTransportExecutor(config: ResponsesTransportExecutorOpti
             );
             responseStream = {
               async *[Symbol.asyncIterator]() {
+                let providerAccepted = false;
                 try {
                   for await (const event of websocket.stream) {
+                    if (!providerAccepted) {
+                      providerAccepted = true;
+                      await notifyProviderStreamOpened({
+                        options,
+                        cancelStream: () => websocket.finish({ keep: false }),
+                      });
+                    }
                     startStream();
                     yield event;
                   }
diff --git a/packages/ai/src/transports/openai-responses-websocket-client.test.ts b/packages/ai/src/transports/openai-responses-websocket-client.test.ts
index a1a61f687656..bd31e09c834f 100644
--- a/packages/ai/src/transports/openai-responses-websocket-client.test.ts
+++ b/packages/ai/src/transports/openai-responses-websocket-client.test.ts
@@ -14,6 +14,10 @@ import {
   responsesPromptObserver,
   type ResponsesPromptObservation,
 } from "./openai-responses-contracts.js";
+import {
+  withProviderAcceptanceObserver,
+  type ProviderAcceptance,
+} from "./transport-stream-shared.js";
 
 type StreamMessage =
   | { type: "open" }
@@ -268,6 +272,7 @@ async function run(
     headers?: Record<string, string>;
     observations?: ResponsesPromptObservation[];
     onCompactionRejected?: () => void;
+    acceptanceObserver?: (acceptance: ProviderAcceptance) => void;
   } = {},
 ): Promise<AssistantMessage> {
   const options = {
@@ -279,6 +284,9 @@ async function run(
     headers: overrides.headers,
     onCompactionRejected: overrides.onCompactionRejected,
   };
+  if (overrides.acceptanceObserver) {
+    withProviderAcceptanceObserver(options, overrides.acceptanceObserver);
+  }
   if (overrides.observations) {
     responsesPromptObserver.set(options, (observation) =>
       overrides.observations?.push(observation),
@@ -341,6 +349,39 @@ describe("native OpenAI Responses WebSocket client integration", () => {
     configureAiTransportHost(initialHost);
   });
 
+  it("reports WebSocket acceptance without fabricated HTTP metadata", async () => {
+    transportState.responseBatches.push([message(completedEvent("resp_accepted", "ok"))]);
+    const acceptanceObserver = vi.fn();
+
+    const result = await run(
+      { messages: [userMessage("hello", 1)], tools: [] },
+      { acceptanceObserver },
+    );
+
+    expect(result.stopReason).toBe("stop");
+    expect(acceptanceObserver).toHaveBeenCalledWith({ kind: "provider_stream_opened" });
+  });
+
+  it("closes the WebSocket when acceptance observation fails", async () => {
+    transportState.responseBatches.push([message(completedEvent("resp_rejected", "ignored"))]);
+    const hookError = new Error("acceptance observer failed");
+
+    const result = await run(
+      { messages: [userMessage("hello", 1)], tools: [] },
+      {
+        acceptanceObserver: () => {
+          throw hookError;
+        },
+      },
+    );
+
+    expect(result).toMatchObject({
+      stopReason: "error",
+      errorMessage: "acceptance observer failed",
+    });
+    expect(transportState.websocketCloseCount).toBe(1);
+  });
+
   it("continues past provider-only output metadata with one socket and only new input", async () => {
     transportState.responseBatches.push(
       [message(completedEvent("resp_1", "first answer"))],
diff --git a/packages/ai/src/transports/openai-transport-shared.ts b/packages/ai/src/transports/openai-transport-shared.ts
index 4be60f9ff045..cf619c0640d8 100644
--- a/packages/ai/src/transports/openai-transport-shared.ts
+++ b/packages/ai/src/transports/openai-transport-shared.ts
@@ -15,7 +15,7 @@ import type { BaseOpenAIStreamOptions } from "../provider-options.js";
 /** Shared options, usage shape, cache identity, ordering, and stream scheduling for OpenAI APIs. */
 import { clampOpenAIPromptCacheKey } from "../providers/openai-prompt-cache.js";
 import { headersToRecord } from "../utils/headers.js";
-import { transportAbortError } from "./transport-stream-shared.js";
+import { notifyProviderHttpResponse, transportAbortError } from "./transport-stream-shared.js";
 
 export { sortPromptCacheToolsByName as sortTransportToolsByName } from "../utils/prompt-cache-stability.js";
 
@@ -230,6 +230,14 @@ export function createOpenAIResponseHook(
     : undefined;
 }
 
+export function createOpenAIProviderAcceptanceHook(
+  options: Pick<BaseOpenAIStreamOptions, "onResponse" | "signal"> | undefined,
+  response: Response,
+  model: Model,
+): () => Promise<void> {
+  return () => notifyProviderHttpResponse({ options, response, model });
+}
+
 type ModelStreamCooperativeScheduler = {
   afterEvent: () => Promise<void>;
 };
diff --git a/packages/ai/src/transports/transport-stream-shared.acceptance.test.ts b/packages/ai/src/transports/transport-stream-shared.acceptance.test.ts
new file mode 100644
index 000000000000..620601780b0c
--- /dev/null
+++ b/packages/ai/src/transports/transport-stream-shared.acceptance.test.ts
@@ -0,0 +1,143 @@
+import type { Model, StreamOptions } from "@openclaw/llm-core";
+import { describe, expect, it, vi } from "vitest";
+import {
+  copyProviderAcceptanceObserver,
+  notifyProviderHttpMetadata,
+  notifyProviderHttpResponse,
+  notifyProviderStreamOpened,
+  withProviderAcceptanceObserver,
+  type ProviderAcceptance,
+} from "./transport-stream-shared.js";
+
+const model = { id: "acceptance-test", provider: "test" } as Model;
+
+function observeAcceptance(
+  observer: (acceptance: ProviderAcceptance) => void,
+  options: StreamOptions = {},
+): StreamOptions {
+  return withProviderAcceptanceObserver(options, observer);
+}
+
+describe("private provider acceptance", () => {
+  it("reports a successful HTTP response before the compatibility callback", async () => {
+    const calls: string[] = [];
+    const observer = vi.fn((acceptance: ProviderAcceptance) => {
+      calls.push(acceptance.kind);
+    });
+    const onResponse = vi.fn(() => {
+      calls.push("onResponse");
+    });
+    const options = observeAcceptance(observer, { onResponse });
+    const response = new Response(null, {
+      status: 200,
+      headers: { "x-request-id": "request-1" },
+    });
+
+    await notifyProviderHttpResponse({ options, response, model });
+
+    expect(observer).toHaveBeenCalledWith({
+      kind: "http_response",
+      status: 200,
+      headers: { "x-request-id": "request-1" },
+    });
+    expect(onResponse).toHaveBeenCalledWith(
+      { status: 200, headers: { "x-request-id": "request-1" } },
+      model,
+    );
+    expect(calls).toEqual(["http_response", "onResponse"]);
+  });
+
+  it("reports a rejected HTTP response without marking it accepted", async () => {
+    const observer = vi.fn();
+    const onResponse = vi.fn();
+    const options = observeAcceptance(observer, { onResponse });
+    const response = new Response("rejected", { status: 429 });
+
+    await notifyProviderHttpResponse({ options, response, model });
+
+    expect(observer).not.toHaveBeenCalled();
+    expect(onResponse).toHaveBeenCalledWith(expect.objectContaining({ status: 429 }), model);
+  });
+
+  it.each(["observer", "onResponse"] as const)(
+    "cancels an unread response when the %s fails",
+    async (failureSource) => {
+      const hookError = new Error(`${failureSource} failed`);
+      const cancel = vi.fn();
+      const response = new Response(new ReadableStream<Uint8Array>({ cancel }), { status: 200 });
+      const options =
+        failureSource === "observer"
+          ? observeAcceptance(() => {
+              throw hookError;
+            })
+          : ({ onResponse: () => Promise.reject(hookError) } satisfies StreamOptions);
+
+      await expect(notifyProviderHttpResponse({ options, response, model })).rejects.toBe(
+        hookError,
+      );
+
+      expect(cancel).toHaveBeenCalledWith(hookError);
+    },
+  );
+
+  it("does not wait for unread response cancellation after the observer fails", async () => {
+    const hookError = new Error("acceptance failed");
+    let markCancelStarted!: () => void;
+    const cancelStarted = new Promise<void>((resolve) => {
+      markCancelStarted = resolve;
+    });
+    const response = new Response(
+      new ReadableStream<Uint8Array>({
+        cancel() {
+          markCancelStarted();
+          return new Promise<void>(() => {});
+        },
+      }),
+      { status: 200 },
+    );
+    const options = observeAcceptance(() => {
+      throw hookError;
+    });
+    const notification = notifyProviderHttpResponse({ options, response, model });
+
+    await cancelStarted;
+    await expect(notification).rejects.toBe(hookError);
+  });
+
+  it("reports an opaque stream without canceling it", async () => {
+    const observer = vi.fn();
+    const cancelStream = vi.fn();
+    const options = observeAcceptance(observer);
+
+    await notifyProviderStreamOpened({ options, cancelStream });
+
+    expect(observer).toHaveBeenCalledWith({ kind: "provider_stream_opened" });
+    expect(cancelStream).not.toHaveBeenCalled();
+  });
+
+  it("preserves the observer when built-in wrappers rebuild options", async () => {
+    const observer = vi.fn();
+    const source = observeAcceptance(observer);
+    const target = copyProviderAcceptanceObserver(source, {});
+
+    await notifyProviderStreamOpened({ options: target, cancelStream: vi.fn() });
+
+    expect(observer).toHaveBeenCalledWith({ kind: "provider_stream_opened" });
+  });
+
+  it("cancels a metadata-only SDK stream when its compatibility callback fails", async () => {
+    const hookError = new Error("response callback failed");
+    const cancelStream = vi.fn();
+
+    await expect(
+      notifyProviderHttpMetadata({
+        options: { onResponse: () => Promise.reject(hookError) },
+        response: { status: 200, headers: {} },
+        model,
+        cancelStream,
+      }),
+    ).rejects.toBe(hookError);
+
+    expect(cancelStream).toHaveBeenCalledWith(hookError);
+  });
+});
diff --git a/packages/ai/src/transports/transport-stream-shared.ts b/packages/ai/src/transports/transport-stream-shared.ts
index 87c80d9c6b6e..5f68293ee199 100644
--- a/packages/ai/src/transports/transport-stream-shared.ts
+++ b/packages/ai/src/transports/transport-stream-shared.ts
@@ -3,9 +3,16 @@
  *
  * Sanitizes provider payloads, merges metadata, and formats streamed assistant events.
  */
-import type { AssistantMessage, Usage } from "@openclaw/llm-core";
+import type {
+  AssistantMessage,
+  Model,
+  ProviderResponse,
+  StreamOptions,
+  Usage,
+} from "@openclaw/llm-core";
 import { asNonArrayRecord, asOptionalRecord } from "@openclaw/normalization-core/record-coerce";
 import { createAssistantMessageEventStream } from "../utils/event-stream.js";
+import { headersToRecord } from "../utils/headers.js";
 import { projectProviderError, type ProviderErrorProjection } from "../utils/provider-error.js";
 import { sanitizeSurrogates } from "../utils/sanitize-unicode.js";
 import { parseJsonObjectPreservingUnsafeIntegers } from "./json-unsafe-integers.js";
@@ -152,6 +159,204 @@ export function transportAbortError(signal?: AbortSignal): Error {
     : new Error("Request was aborted");
 }
 
+export type ProviderAcceptance =
+  | {
+      kind: "http_response";
+      status: number;
+      headers: Record<string, string>;
+    }
+  | { kind: "provider_stream_opened" };
+
+type ProviderAcceptanceObserver = (acceptance: ProviderAcceptance) => void;
+type ProviderAcceptanceOptions = Pick<StreamOptions, "onResponse" | "signal">;
+type ProviderStreamCancel = (reason: Error) => void | Promise<void>;
+
+const providerAcceptanceObserver: unique symbol = Symbol("openclaw.providerAcceptanceObserver");
+
+function readProviderAcceptanceObserver(options: unknown): ProviderAcceptanceObserver | undefined {
+  if (options === null || typeof options !== "object") {
+    return undefined;
+  }
+  const descriptor = Object.getOwnPropertyDescriptor(options, providerAcceptanceObserver);
+  const value: unknown = descriptor && "value" in descriptor ? descriptor.value : undefined;
+  return isProviderAcceptanceObserver(value) ? value : undefined;
+}
+
+function isProviderAcceptanceObserver(value: unknown): value is ProviderAcceptanceObserver {
+  return typeof value === "function";
+}
+
+function writeProviderAcceptanceObserver<T extends object>(
+  options: T,
+  observer: ProviderAcceptanceObserver,
+): T {
+  // Keep this enumerable so normal option spreads preserve the private per-call observer.
+  Object.defineProperty(options, providerAcceptanceObserver, {
+    configurable: true,
+    enumerable: true,
+    value: observer,
+  });
+  return options;
+}
+
+/** Attach an OpenClaw-internal provider acceptance observer to one model call. */
+export function withProviderAcceptanceObserver<T extends object>(
+  options: T,
+  observer: ProviderAcceptanceObserver,
+): T {
+  const existing = readProviderAcceptanceObserver(options);
+  return writeProviderAcceptanceObserver(
+    options,
+    existing
+      ? (acceptance) => {
+          observer(acceptance);
+          existing(acceptance);
+        }
+      : observer,
+  );
+}
+
+/** Preserve the private provider acceptance observer when a built-in wrapper rebuilds options. */
+export function copyProviderAcceptanceObserver<T extends object>(source: unknown, target: T): T {
+  const observer = readProviderAcceptanceObserver(source);
+  return observer ? writeProviderAcceptanceObserver(target, observer) : target;
+}
+
+async function awaitProviderLifecycleCallback(
+  callback: (() => void | Promise<void>) | undefined,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (signal?.aborted) {
+    throw transportAbortError(signal);
+  }
+  if (!callback) {
+    return;
+  }
+  const callbackPromise = Promise.resolve().then(callback);
+  if (!signal) {
+    await callbackPromise;
+    return;
+  }
+  let onAbort: (() => void) | undefined;
+  try {
+    await Promise.race([
+      callbackPromise,
+      new Promise<never>((_resolve, reject) => {
+        onAbort = () => reject(transportAbortError(signal));
+        signal.addEventListener("abort", onAbort, { once: true });
+      }),
+    ]);
+  } finally {
+    if (onAbort) {
+      signal.removeEventListener("abort", onAbort);
+    }
+  }
+  if (signal.aborted) {
+    throw transportAbortError(signal);
+  }
+}
+
+function startProviderStreamCancellation(cancelStream: ProviderStreamCancel, error: unknown): void {
+  const reason = error instanceof Error ? error : new Error(String(error));
+  try {
+    // The lifecycle failure remains authoritative. Cleanup must not delay or replace it.
+    void Promise.resolve(cancelStream(reason)).catch(() => undefined);
+  } catch {
+    // A synchronous cleanup failure cannot replace the lifecycle failure either.
+  }
+}
+
+async function awaitProviderLifecycleWithCleanup(params: {
+  run: () => Promise<void>;
+  cancelStream: ProviderStreamCancel;
+}): Promise<void> {
+  try {
+    await params.run();
+  } catch (error) {
+    startProviderStreamCancellation(params.cancelStream, error);
+    throw error;
+  }
+}
+
+/** Report observed HTTP metadata; rejected responses use only onResponse. */
+export async function notifyProviderHttpMetadata(params: {
+  options?: ProviderAcceptanceOptions;
+  response: ProviderResponse;
+  model: Model;
+  cancelStream: ProviderStreamCancel;
+  signal?: AbortSignal;
+}): Promise<void> {
+  const observer = readProviderAcceptanceObserver(params.options);
+  if (!observer && !params.options?.onResponse) {
+    return;
+  }
+  const { status, headers } = params.response;
+  const signal = params.signal ?? params.options?.signal;
+  const accepted = status >= 200 && status < 300;
+  await awaitProviderLifecycleWithCleanup({
+    cancelStream: params.cancelStream,
+    run: async () => {
+      await awaitProviderLifecycleCallback(
+        accepted && observer
+          ? () => observer({ kind: "http_response", status, headers })
+          : undefined,
+        signal,
+      );
+      await awaitProviderLifecycleCallback(
+        params.options?.onResponse
+          ? () => params.options?.onResponse?.({ status, headers }, params.model)
+          : undefined,
+        signal,
+      );
+    },
+  });
+}
+
+/** Report a real HTTP response before body consumption. */
+export async function notifyProviderHttpResponse(params: {
+  options?: ProviderAcceptanceOptions;
+  response: Response;
+  model: Model;
+  cancelStream?: ProviderStreamCancel;
+  signal?: AbortSignal;
+}): Promise<void> {
+  await notifyProviderHttpMetadata({
+    options: params.options,
+    response: {
+      status: params.response.status,
+      headers: headersToRecord(params.response.headers),
+    },
+    model: params.model,
+    signal: params.signal,
+    cancelStream: (reason) => {
+      if (params.cancelStream) {
+        startProviderStreamCancellation(params.cancelStream, reason);
+      }
+      return params.response.body?.cancel(reason);
+    },
+  });
+}
+
+/** Report an accepted SDK stream when the SDK does not expose HTTP metadata. */
+export async function notifyProviderStreamOpened(params: {
+  options?: Pick<StreamOptions, "signal">;
+  cancelStream: ProviderStreamCancel;
+  signal?: AbortSignal;
+}): Promise<void> {
+  const observer = readProviderAcceptanceObserver(params.options);
+  if (!observer) {
+    return;
+  }
+  await awaitProviderLifecycleWithCleanup({
+    cancelStream: params.cancelStream,
+    run: () =>
+      awaitProviderLifecycleCallback(
+        () => observer({ kind: "provider_stream_opened" }),
+        params.signal ?? params.options?.signal,
+      ),
+  });
+}
+
 /** Run a provider-response hook before start/body consumption inside the first-event deadline. */
 export function withProviderResponseHook<T = never>(params: {
   stream?: AsyncIterable<T>;
@@ -162,27 +367,11 @@ export function withProviderResponseHook<T = never>(params: {
 }): AsyncIterable<T> {
   return {
     async *[Symbol.asyncIterator]() {
-      let onAbort: (() => void) | undefined;
       try {
-        if (params.signal.aborted) {
-          throw transportAbortError(params.signal);
-        }
-        if (params.hook) {
-          await Promise.race([
-            Promise.resolve().then(params.hook),
-            new Promise<never>((_resolve, reject) => {
-              onAbort = () => reject(transportAbortError(params.signal));
-              params.signal.addEventListener("abort", onAbort, { once: true });
-            }),
-          ]);
-        }
+        await awaitProviderLifecycleCallback(params.hook, params.signal);
       } catch (error) {
         params.abort(error instanceof Error ? error : new Error(String(error)));
         throw error;
-      } finally {
-        if (onAbort) {
-          params.signal.removeEventListener("abort", onAbort);
-        }
       }
       if (params.signal.aborted) {
         throw transportAbortError(params.signal);
diff --git a/src/agents/embedded-agent-runner/run/attempt.model-diagnostic-lifecycle.test.ts b/src/agents/embedded-agent-runner/run/attempt.model-diagnostic-lifecycle.test.ts
index e2cbb8005ef4..9c9e4c0d6639 100644
--- a/src/agents/embedded-agent-runner/run/attempt.model-diagnostic-lifecycle.test.ts
+++ b/src/agents/embedded-agent-runner/run/attempt.model-diagnostic-lifecycle.test.ts
@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 // Coverage for model-call diagnostic events around attempt stream functions.
+import { notifyProviderStreamOpened } from "@openclaw/ai/transports";
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import type { StreamFn } from "openclaw/plugin-sdk/agent-core";
 import { createRequireRecord } from "openclaw/plugin-sdk/test-fixtures";
@@ -172,7 +173,7 @@ describe("wrapStreamFnWithDiagnosticModelCallEvents lifecycle", () => {
     expect(events[0]?.status).toBeUndefined();
   });
 
-  it("records provider response status and preserves the original response callback", async () => {
+  it("records legacy response status without inferring provider acceptance", async () => {
     const originalOnResponse = vi.fn(async () => undefined);
     const wrapped = wrapStreamFnWithDiagnosticModelCallEvents(
       ((
@@ -212,9 +213,44 @@ describe("wrapStreamFnWithDiagnosticModelCallEvents lifecycle", () => {
       type: "provider.request",
       ok: true,
       status: 200,
+      attributes: {
+        providerAccepted: false,
+      },
     });
   });
 
+  it("records provider acceptance when an SDK hides HTTP metadata", async () => {
+    const wrapped = wrapStreamFnWithDiagnosticModelCallEvents(
+      ((
+        _model: Parameters<StreamFn>[0],
+        _context: Parameters<StreamFn>[1],
+        options: Parameters<StreamFn>[2],
+      ) => notifyProviderStreamOpened({ options, cancelStream: vi.fn() })) as unknown as StreamFn,
+      {
+        runId: "run-timeline-accepted",
+        provider: "google",
+        model: "gemini-2.5-pro",
+        api: "google-generative-ai",
+        trace: createDiagnosticTraceContext(),
+        nextCallId: () => "call-timeline-accepted",
+      },
+    );
+
+    const events = await collectProviderTimelineEvents(async () => {
+      await wrapped({ id: "gemini-2.5-pro" } as never, {} as never, {});
+    });
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      type: "provider.request",
+      ok: true,
+      attributes: {
+        providerAccepted: true,
+        providerAcceptanceKind: "provider_stream_opened",
+      },
+    });
+    expect(events[0]?.status).toBeUndefined();
+  });
+
   it("writes Unicode-safe bounded attributes to the provider timeline JSONL", async () => {
     const modelPrefix = "m".repeat(255);
     const exactBoundary = "b".repeat(256);
diff --git a/src/agents/embedded-agent-runner/run/attempt.model-diagnostic-lifecycle.ts b/src/agents/embedded-agent-runner/run/attempt.model-diagnostic-lifecycle.ts
index e3dcb3b35a5a..7062fcba8717 100644
--- a/src/agents/embedded-agent-runner/run/attempt.model-diagnostic-lifecycle.ts
+++ b/src/agents/embedded-agent-runner/run/attempt.model-diagnostic-lifecycle.ts
@@ -1,3 +1,4 @@
+import { withProviderAcceptanceObserver, type ProviderAcceptance } from "@openclaw/ai/transports";
 import { isPromiseLike } from "@openclaw/normalization-core/promise-like";
 import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
 import { fireAndForgetBoundedHook } from "../../../hooks/fire-and-forget.js";
@@ -85,6 +86,7 @@ export type ModelCallUsage = NonNullable<
 >;
 export type ModelCallObservationState = {
   requestPayloadBytes?: number;
+  providerAcceptanceKind?: ProviderAcceptance["kind"];
   responseStatus?: number;
   responseStreamBytes: number;
   timeToFirstByteMs?: number;
@@ -154,6 +156,7 @@ function emitProviderRequestTimelineEvent(
   durationMs: number,
   ok: boolean,
   responseStatus: number | undefined,
+  providerAcceptanceKind: ModelCallObservationState["providerAcceptanceKind"],
 ): void {
   const provider = boundedTimelineAttribute(eventBase.provider);
   const model = boundedTimelineAttribute(eventBase.model);
@@ -174,6 +177,8 @@ function emitProviderRequestTimelineEvent(
       ...(model ? { model } : {}),
       ...(api ? { api } : {}),
       ...(transport ? { transport } : {}),
+      providerAccepted: providerAcceptanceKind !== undefined,
+      ...(providerAcceptanceKind ? { providerAcceptanceKind } : {}),
     },
   });
 }
@@ -291,6 +296,7 @@ function emitModelCallCompleted(
     durationMs,
     true,
     observer.state.responseStatus,
+    observer.state.providerAcceptanceKind,
   );
   emitCoreModelRequestEndedDiagnosticEvent(
     {
@@ -329,7 +335,14 @@ function emitModelCallError(
   const errorStatus = diagnosticHttpStatusCode(err);
   const responseStatus =
     observer.state.responseStatus ?? (errorStatus === undefined ? undefined : Number(errorStatus));
-  emitProviderRequestTimelineEvent(eventBase, startedAt, durationMs, false, responseStatus);
+  emitProviderRequestTimelineEvent(
+    eventBase,
+    startedAt,
+    durationMs,
+    false,
+    responseStatus,
+    observer.state.providerAcceptanceKind,
+  );
   emitCoreModelRequestEndedDiagnosticEvent(
     {
       type: "model.call.error",
@@ -393,13 +406,19 @@ function withDiagnosticRequestContext(
   if (traceparent) {
     headers[TRACEPARENT_HEADER_NAME] = traceparent;
   }
-  return {
+  const requestOptions = {
     ...options,
     requestId: callId,
     ...((options?.headers || traceparent) && { headers }),
     onPayload,
     onResponse,
   };
+  return withProviderAcceptanceObserver(requestOptions, (acceptance) => {
+    observer.state.providerAcceptanceKind = acceptance.kind;
+    if (acceptance.kind === "http_response") {
+      observer.state.responseStatus = acceptance.status;
+    }
+  });
 }
 
 export function createModelLifecycle(params: {
diff --git a/src/plugin-sdk/provider-transport-runtime.ts b/src/plugin-sdk/provider-transport-runtime.ts
index 407967b34f61..4d54b86b31ed 100644
--- a/src/plugin-sdk/provider-transport-runtime.ts
+++ b/src/plugin-sdk/provider-transport-runtime.ts
@@ -17,6 +17,7 @@ export {
 } from "@openclaw/ai/internal/shared";
 export {
   coerceTransportToolCallArguments,
+  copyProviderAcceptanceObserver,
   createEmptyTransportUsage,
   createWritableTransportEventStream,
   failTransportStream,
@@ -24,7 +25,12 @@ export {
   finalizeTransportStream,
   MALFORMED_STREAMING_FRAGMENT_ERROR_MESSAGE,
   mergeTransportHeaders,
+  notifyProviderHttpMetadata,
+  notifyProviderHttpResponse,
+  notifyProviderStreamOpened,
   parseTerminalToolCallArguments,
   sanitizeTransportPayloadText,
+  withProviderAcceptanceObserver,
+  type ProviderAcceptance,
   type WritableTransportStream,
 } from "@openclaw/ai/transports";
diff --git a/ui/src/e2e/new-session-page.draft-handoff.e2e.test.ts b/ui/src/e2e/new-session-page.draft-handoff.e2e.test.ts
index fad327b36089..70e01a055df2 100644
--- a/ui/src/e2e/new-session-page.draft-handoff.e2e.test.ts
+++ b/ui/src/e2e/new-session-page.draft-handoff.e2e.test.ts
@@ -6,6 +6,7 @@ import {
   createNewSessionPageE2eSuite,
   createdSessionListResult,
   installMockGateway,
+  waitForCommittedNewSessionDraft,
 } from "./new-session-page.test-support.ts";
 
 const suite = createNewSessionPageE2eSuite();
@@ -63,6 +64,7 @@ suite.define(() => {
         .locator(".agent-chat__photo-input")
         .setInputFiles(path.join(process.cwd(), "ui/public/apple-touch-icon.png"));
       await pageB.getByRole("button", { name: `Open image ${durableFileName}` }).waitFor();
+      await waitForCommittedNewSessionDraft(pageB, durableText, 1);
       await pageB.reload();
       await expect.poll(() => messageB.inputValue()).toBe(durableText);
       await pageB.getByRole("button", { name: `Open image ${durableFileName}` }).waitFor();
diff --git a/ui/src/pages/chat/chat-responsive.browser.test.ts b/ui/src/pages/chat/chat-responsive.browser.test.ts
index 083c5f327cc9..12be9b32b605 100644
--- a/ui/src/pages/chat/chat-responsive.browser.test.ts
+++ b/ui/src/pages/chat/chat-responsive.browser.test.ts
@@ -1299,8 +1299,9 @@ describeBrowserLayout.concurrent("chat responsive browser layout", () => {
         };
       });
 
-      expect(gaps.before).toBeCloseTo(expectedGap, 0);
-      expect(gaps.after).toBeCloseTo(expectedGap, 0);
+      // Browser font metrics can shift subpixel geometry; one CSS pixel is the layout boundary.
+      expect(Math.abs(gaps.before - expectedGap)).toBeLessThan(1);
+      expect(Math.abs(gaps.after - expectedGap)).toBeLessThan(1);
     } finally {
       await closeBrowserPage(page);
     }

From 4343b38ce7630fddaa16bfb72262e071d25424f6 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 09:34:18 -0700
Subject: [PATCH 033/124] perf(googlechat): render bullet markers in one pass
 (#127274)

Co-authored-by: Amp <amp@ampcode.com>
---
 extensions/googlechat/src/format.test.ts | 22 +++++++++++++++++++++-
 extensions/googlechat/src/format.ts      | 16 ++++++++++++----
 2 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/extensions/googlechat/src/format.test.ts b/extensions/googlechat/src/format.test.ts
index d2fd5fc2fba1..325ba3eefd80 100644
--- a/extensions/googlechat/src/format.test.ts
+++ b/extensions/googlechat/src/format.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { formatGoogleChatTextChunks, GOOGLE_CHAT_FORMAT_PROFILE } from "./format.js";
 
 const formatGoogleChatText = (text: string) => formatGoogleChatTextChunks(text).join("");
@@ -104,6 +104,26 @@ describe("formatGoogleChatText", () => {
     expect(formatGoogleChatText("   - top-level")).toBe("* top-level");
   });
 
+  it("keeps dense bullet-list formatting work bounded", () => {
+    const input = Array.from({ length: 1_000 }, (_, index) => `- row ${index}`).join("\n");
+    const expected = input.replace(/^- /gmu, "* ");
+    const sliceSpy = vi.spyOn(String.prototype, "slice");
+    let fullMessagePrefixSlices = 0;
+    try {
+      expect(formatGoogleChatText(input)).toBe(expected);
+      fullMessagePrefixSlices = sliceSpy.mock.calls.reduce((count, [start, end], index) => {
+        const source = sliceSpy.mock.contexts[index];
+        return String(source).length === input.length && start === 0 && end !== undefined
+          ? count + 1
+          : count;
+      }, 0);
+    } finally {
+      sliceSpy.mockRestore();
+    }
+
+    expect(fullMessagePrefixSlices).toBeLessThan(50);
+  });
+
   it("neutralizes nested markup inside native link labels", () => {
     expect(formatGoogleChatText("[x > y](https://example.com)")).toBe(
       "<https://example.com|x ＞ y>",
diff --git a/extensions/googlechat/src/format.ts b/extensions/googlechat/src/format.ts
index b7af92228549..cde1e4eee0c5 100644
--- a/extensions/googlechat/src/format.ts
+++ b/extensions/googlechat/src/format.ts
@@ -113,15 +113,23 @@ function projectGoogleChatLinkLabels(ir: MarkdownIR): MarkdownIR {
 }
 
 function markGoogleChatBulletLists(ir: MarkdownIR, markerToken: string): MarkdownIR {
-  let text = ir.text;
+  let characters: string[] | undefined;
   for (const item of ir.listItems ?? []) {
     const marker = item.listMarker;
-    if (item.kind !== "bullet" || !marker || text.slice(marker.start, marker.end) !== "• ") {
+    if (
+      item.kind !== "bullet" ||
+      !marker ||
+      marker.end !== marker.start + 2 ||
+      ir.text[marker.start] !== "•" ||
+      ir.text[marker.start + 1] !== " "
+    ) {
       continue;
     }
-    text = `${text.slice(0, marker.start)}${markerToken}${text.slice(marker.end)}`;
+    characters ??= ir.text.split("");
+    characters[marker.start] = markerToken[0] ?? "";
+    characters[marker.start + 1] = markerToken[1] ?? "";
   }
-  return text === ir.text ? ir : { ...ir, text };
+  return characters ? { ...ir, text: characters.join("") } : ir;
 }
 
 function projectUnsafeCodeFallbacks(ir: MarkdownIR): MarkdownIR {

From 781ded80d62499dc123a97e4eb534ce13791e034 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 09:52:20 -0700
Subject: [PATCH 034/124] fix(plugins): register static node-host commands
 without activation (#127043)

The node host resolves its plugin registry via loadPluginRegistryHandle
(activate:false). Since #117587 static definition.nodeHostCommands only
registered under runFullActivationOnlyRegistrations, so headless nodes
silently lost browser.proxy (and the browser/file caps), breaking the
meeting-bot chain with 'No connected Google Meet-capable node with
browser proxy'. Register node-host commands in every load mode; each
command keeps its own isAvailable gate. reload and security audit
collectors stay activation-only.
---
 src/plugins/loader-runtime-candidate.ts       | 10 ++--
 src/plugins/loader.node-host-commands.test.ts | 49 +++++++++++++++++++
 2 files changed, 56 insertions(+), 3 deletions(-)
 create mode 100644 src/plugins/loader.node-host-commands.test.ts

diff --git a/src/plugins/loader-runtime-candidate.ts b/src/plugins/loader-runtime-candidate.ts
index ee139e75563a..92fa090aed09 100644
--- a/src/plugins/loader-runtime-candidate.ts
+++ b/src/plugins/loader-runtime-candidate.ts
@@ -507,13 +507,17 @@ export function loadRuntimePluginCandidate(params: {
     }
     return;
   }
+  // Node-host commands register in every load mode: the node host resolves its
+  // registry without activation (loadPluginRegistryHandle), and each command is
+  // already availability-gated per invocation. Gating them on full activation
+  // silently strips static registrations like browser.proxy from headless nodes.
+  for (const nodeHostCommand of definition?.nodeHostCommands ?? []) {
+    params.registryBuilder.registerNodeHostCommand(record, nodeHostCommand);
+  }
   if (registrationPlan.runFullActivationOnlyRegistrations) {
     if (definition?.reload) {
       params.registryBuilder.registerReload(record, definition.reload);
     }
-    for (const nodeHostCommand of definition?.nodeHostCommands ?? []) {
-      params.registryBuilder.registerNodeHostCommand(record, nodeHostCommand);
-    }
     for (const collector of definition?.securityAuditCollectors ?? []) {
       params.registryBuilder.registerSecurityAuditCollector(record, collector);
     }
diff --git a/src/plugins/loader.node-host-commands.test.ts b/src/plugins/loader.node-host-commands.test.ts
new file mode 100644
index 000000000000..a98c93e8ddeb
--- /dev/null
+++ b/src/plugins/loader.node-host-commands.test.ts
@@ -0,0 +1,49 @@
+/** Verifies static plugin nodeHostCommands survive non-activating registry loads (node-host path). */
+import { afterAll, afterEach, expect, it } from "vitest";
+import {
+  cleanupPluginLoaderFixturesForTest,
+  loadOpenClawPlugins,
+  resetPluginLoaderTestStateForTest,
+  useNoBundledPlugins,
+  writePlugin,
+} from "./loader.test-fixtures.js";
+
+afterEach(resetPluginLoaderTestStateForTest);
+afterAll(cleanupPluginLoaderFixturesForTest);
+
+// The node host resolves its registry via loadPluginRegistryHandle (activate:false).
+// Static nodeHostCommands (e.g. the browser plugin's browser.proxy) must register
+// there too, or headless meeting/browser nodes silently lose their surface.
+it("registers static nodeHostCommands without activation", () => {
+  useNoBundledPlugins();
+  const plugin = writePlugin({
+    id: "node-surface",
+    body: `module.exports = {
+      id: "node-surface",
+      nodeHostCommands: [{
+        command: "nodesurface.proxy",
+        cap: "node-surface",
+        handle: async () => "ok",
+      }],
+      register() {},
+    };`,
+  });
+
+  const registry = loadOpenClawPlugins({
+    cache: false,
+    activate: false,
+    workspaceDir: plugin.dir,
+    config: {
+      plugins: {
+        load: { paths: [plugin.file] },
+        allow: [plugin.id],
+      },
+    },
+    onlyPluginIds: [plugin.id],
+  });
+
+  expect(registry.plugins.find((entry) => entry.id === plugin.id)?.status).toBe("loaded");
+  expect(registry.nodeHostCommands.map((entry) => entry.command.command)).toContain(
+    "nodesurface.proxy",
+  );
+});

From 6448550898c2c836e14249213d22c491f7111063 Mon Sep 17 00:00:00 2001
From: Josh Lehman <josh@martian.engineering>
Date: Fri, 21 Aug 2026 10:00:40 -0700
Subject: [PATCH 035/124] fix(codex): preserve project instructions in
 restricted turns (#126891)

* fix(codex): preserve restricted project instructions

* fix(codex): preserve ring-zero context isolation

* docs(codex): explain restricted turns and ring zero
---
 docs/plugins/codex-harness-reference.md       | 59 ++++++++++++++++++-
 docs/plugins/codex-harness-runtime.md         | 33 ++++++-----
 docs/plugins/codex-harness.md                 | 54 ++++++++++++++++-
 .../src/app-server/attempt-context.test.ts    | 34 +++++++++++
 .../codex/src/app-server/attempt-context.ts   | 11 +++-
 .../src/app-server/run-attempt-context.ts     |  7 ++-
 .../codex/src/app-server/run-attempt.test.ts  |  8 +++
 .../codex/src/app-server/session-binding.ts   |  4 +-
 .../src/app-server/thread-lifecycle.test.ts   | 48 +++++++++++++++
 .../codex/src/app-server/thread-requests.ts   | 36 +++++------
 10 files changed, 253 insertions(+), 41 deletions(-)

diff --git a/docs/plugins/codex-harness-reference.md b/docs/plugins/codex-harness-reference.md
index 2680a2e13451..45fdec3ff0f9 100644
--- a/docs/plugins/codex-harness-reference.md
+++ b/docs/plugins/codex-harness-reference.md
@@ -808,14 +808,67 @@ the fallback catalog:
 }
 ```
 
+## Restricted turns
+
+The Codex harness evaluates the effective tool policy for every turn. It marks
+the turn policy-restricted when any explicit policy would otherwise leave a
+Codex-native capability outside the OpenClaw policy boundary.
+
+Restriction sources include global, provider, agent, group, sender, sandbox,
+subagent, inherited, scheduled/runtime, and per-run tool policies. A finite
+allowlist always restricts the native surface. A deny list restricts it when an
+expanded entry is unknown or absent from the audited safe-deny set; this includes
+wildcards and tool groups containing any unsafe entry. `disableTools` becomes an
+empty per-run allowlist and therefore also restricts the native surface. Default
+tool-profile narrowing is not an explicit restriction and does not activate this
+mode.
+
+The current audited safe-deny names are:
+
+```text
+automations, canvas, dashboard, gateway, heartbeat_respond, image_generate,
+memory_get, memory_search, message, music_generate, show_widget, skill_workshop,
+tts, video_generate, web_fetch, x_search
+```
+
+A policy containing only those denies stays on the normal Codex native surface;
+the harness applies the named OpenClaw denial directly. Any other deny fails
+closed into the restricted surface. For example, `tools.deny: ["nodes"]`
+restricts the native surface because `nodes` is not in the audited set.
+
+Policy-restricted turns have no Codex environment selection or native Code Mode.
+OpenClaw disables inherited and configured MCP servers, attests that they remain
+disabled, disables native hook relays, and applies the effective policy to its
+dynamic tools. A temporary restriction on an existing session uses a transient
+Codex thread and preserves the unrestricted binding for later resume.
+
+Ring zero is not a configurable policy profile. It is the host-scoped system
+agent path used by OpenClaw setup and repair flows. The host must activate the
+system-agent authority and provide the exact single-tool allowlist
+`["openclaw"]`. Ring zero applies the restricted tool surface plus host-authored
+base instructions and zero project-document budget. It also suppresses
+OpenClaw's `AGENTS.md` developer-instruction carrier, so ambient workspace
+instructions cannot enter the setup/repair turn.
+
+Message-only source replies also use the restricted tool surface. Lightweight
+bootstrap turns and tool-disabled internal turns additionally set the project-
+document budget to zero. These modes are separate inputs even when their final
+thread configuration overlaps.
+
 ## Workspace bootstrap files
 
-Codex handles `AGENTS.md` itself through native project-doc discovery.
+Codex normally handles `AGENTS.md` itself through native project-doc discovery.
 OpenClaw does not write synthetic Codex project-doc files or depend on Codex
 fallback filenames for persona files, because Codex fallbacks only apply when
-`AGENTS.md` is missing.
+`AGENTS.md` is missing. Ordinary policy-restricted turns have no native
+filesystem environment, so OpenClaw instead sends the bounded workspace
+`AGENTS.md` snapshot as thread-level developer instructions. Ring-zero,
+lightweight, message-only, and tool-disabled internal turns suppress that
+carrier.
 
-For OpenClaw workspace parity, local tool notes live in the `## Tools` section of `AGENTS.md` and ride Codex's native project-doc discovery. The Codex harness forwards the other bootstrap files as developer instructions:
+For OpenClaw workspace parity, local tool notes live in the `## Tools` section
+of `AGENTS.md` and normally ride Codex's native project-doc discovery. The
+Codex harness forwards the other bootstrap files as developer instructions:
 
 - `SOUL.md`, `IDENTITY.md`, and `USER.md` are forwarded as **turn-scoped**
   collaboration instructions. Native Codex subagents do not inherit them,
diff --git a/docs/plugins/codex-harness-runtime.md b/docs/plugins/codex-harness-runtime.md
index f61eb3dfb0ea..6eb7d708309b 100644
--- a/docs/plugins/codex-harness-runtime.md
+++ b/docs/plugins/codex-harness-runtime.md
@@ -45,8 +45,11 @@ it uses Codex-flavored OpenAI auth or transport.
 OpenClaw starts and resumes native Codex threads with Codex's built-in
 personality disabled (`personality: "none"`) so workspace personality files
 and OpenClaw agent identity stay authoritative. Native Codex keeps Codex-owned
-base/model instructions and project-doc loading otherwise. Lightweight
-OpenClaw runs (for example cron) still suppress project-doc loading.
+base/model instructions and project-doc loading otherwise. An ordinary
+policy-restricted turn has no native filesystem environment, so OpenClaw carries
+the bounded workspace `AGENTS.md` snapshot as thread-level developer
+instructions instead. Lightweight, ring-zero, message-only, and tool-disabled
+internal turns suppress project-doc loading and that fallback carrier.
 
 OpenClaw developer instructions cover OpenClaw runtime concerns: source-channel
 delivery, OpenClaw dynamic tools, ACP delegation, adapter context, and the
@@ -224,19 +227,19 @@ for configuration and local-only transport restrictions.
 
 Supported in Codex runtime v1:
 
-| Surface                                       | Support                                                                          | Why                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| --------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| OpenAI model loop through Codex               | Supported                                                                        | Codex app-server owns the OpenAI turn, native thread resume, and native tool continuation.                                                                                                                                                                                                                                                                                                                                                                                          |
-| OpenClaw channel routing and delivery         | Supported                                                                        | Telegram, Discord, Slack, WhatsApp, iMessage, and other channels stay outside the model runtime.                                                                                                                                                                                                                                                                                                                                                                                    |
-| OpenClaw dynamic tools                        | Supported                                                                        | Codex asks OpenClaw to execute these tools, so OpenClaw stays in the execution path.                                                                                                                                                                                                                                                                                                                                                                                                |
-| Prompt and context plugins                    | Supported                                                                        | OpenClaw projects OpenClaw-specific prompt/context into the Codex turn while leaving Codex-owned base, model, and configured project-doc prompts in the native Codex lane. OpenClaw disables Codex's built-in personality for native threads so agent workspace personality files remain authoritative. Native Codex developer instructions accept only command guidance explicitly scoped to `codex_app_server`; legacy global command hints remain for non-Codex prompt surfaces. |
-| Context engine lifecycle                      | Supported                                                                        | Assemble, ingest, and after-turn maintenance run around Codex turns. Context engines do not replace native Codex compaction.                                                                                                                                                                                                                                                                                                                                                        |
-| Dynamic tool hooks                            | Supported                                                                        | `before_tool_call`, `after_tool_call`, and tool-result middleware run around OpenClaw-owned dynamic tools.                                                                                                                                                                                                                                                                                                                                                                          |
-| Lifecycle hooks                               | Supported as adapter observations                                                | `llm_input`, `llm_output`, `agent_end`, `before_compaction`, and `after_compaction` fire with honest Codex-mode payloads.                                                                                                                                                                                                                                                                                                                                                           |
-| Final-answer revision gate                    | Supported through native hook relay                                              | Codex `Stop` is relayed to `before_agent_finalize`; `revise` asks Codex for one more model pass before finalization.                                                                                                                                                                                                                                                                                                                                                                |
-| Native shell, patch, and MCP block or observe | Supported through native hook relay                                              | Codex `PreToolUse` and `PostToolUse` are relayed for committed native tool surfaces, including MCP payloads on the pinned Codex app-server. Blocking is supported; argument rewriting is not.                                                                                                                                                                                                                                                                                       |
-| Native permission policy                      | Supported through Codex app-server approvals and compatibility native hook relay | Codex app-server approval requests route through OpenClaw after Codex review. The `PermissionRequest` native hook relay is opt-in for native approval modes because Codex emits it before guardian review.                                                                                                                                                                                                                                                                          |
-| App-server trajectory capture                 | Supported                                                                        | OpenClaw records the request it sent to app-server and the app-server notifications it receives.                                                                                                                                                                                                                                                                                                                                                                                    |
+| Surface                                       | Support                                                                          | Why                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| --------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| OpenAI model loop through Codex               | Supported                                                                        | Codex app-server owns the OpenAI turn, native thread resume, and native tool continuation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| OpenClaw channel routing and delivery         | Supported                                                                        | Telegram, Discord, Slack, WhatsApp, iMessage, and other channels stay outside the model runtime.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| OpenClaw dynamic tools                        | Supported                                                                        | Codex asks OpenClaw to execute these tools, so OpenClaw stays in the execution path.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Prompt and context plugins                    | Supported                                                                        | OpenClaw projects OpenClaw-specific prompt/context into the Codex turn while normally leaving Codex-owned base, model, and configured project-doc prompts in the native Codex lane. For ordinary policy-restricted turns without a native filesystem environment, OpenClaw carries the bounded workspace `AGENTS.md` snapshot as thread-level developer instructions. Ring-zero and other context-restricted internal modes suppress both paths. OpenClaw disables Codex's built-in personality for native threads so agent workspace personality files remain authoritative. Native Codex developer instructions accept only command guidance explicitly scoped to `codex_app_server`; legacy global command hints remain for non-Codex prompt surfaces. |
+| Context engine lifecycle                      | Supported                                                                        | Assemble, ingest, and after-turn maintenance run around Codex turns. Context engines do not replace native Codex compaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Dynamic tool hooks                            | Supported                                                                        | `before_tool_call`, `after_tool_call`, and tool-result middleware run around OpenClaw-owned dynamic tools.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Lifecycle hooks                               | Supported as adapter observations                                                | `llm_input`, `llm_output`, `agent_end`, `before_compaction`, and `after_compaction` fire with honest Codex-mode payloads.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Final-answer revision gate                    | Supported through native hook relay                                              | Codex `Stop` is relayed to `before_agent_finalize`; `revise` asks Codex for one more model pass before finalization.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Native shell, patch, and MCP block or observe | Supported through native hook relay                                              | Codex `PreToolUse` and `PostToolUse` are relayed for committed native tool surfaces, including MCP payloads on the pinned Codex app-server. Blocking is supported; argument rewriting is not.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Native permission policy                      | Supported through Codex app-server approvals and compatibility native hook relay | Codex app-server approval requests route through OpenClaw after Codex review. The `PermissionRequest` native hook relay is opt-in for native approval modes because Codex emits it before guardian review.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| App-server trajectory capture                 | Supported                                                                        | OpenClaw records the request it sent to app-server and the app-server notifications it receives.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 
 Not supported in Codex runtime v1:
 
diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md
index b4f720ea8f30..5ff04206fcfc 100644
--- a/docs/plugins/codex-harness.md
+++ b/docs/plugins/codex-harness.md
@@ -271,13 +271,63 @@ Changing auth order does not make a custom, Completions, HTTP, or
 request-overridden route Codex-compatible. Valid model-scoped Fast-mode and
 cutoff controls are runtime controls, not request overrides.
 
+### Restricted turns and ring zero
+
+OpenClaw applies Codex restrictions per turn, not as a permanent session mode.
+An existing session can therefore run one restricted turn and return to its
+normal Codex thread on the next unrestricted turn. When a restriction is
+temporary, OpenClaw preserves the normal thread binding and uses a temporary
+restricted thread where necessary.
+
+An ordinary **policy-restricted turn** occurs when an explicit OpenClaw tool
+policy cannot be mapped safely onto Codex's native tool surface. Common
+triggers include:
+
+- a finite `tools.allow` list or an internal per-run allowlist
+- `disableTools` or a sender/group policy that denies all tools
+- a `tools.deny` entry with a wildcard, tool group, unknown name, or name that
+  is not in the Codex harness's audited safe-deny set
+- an applicable agent, provider, group, sender, sandbox, subagent, inherited,
+  scheduled, or runtime tool policy with one of those restrictions
+
+Default tool-profile narrowing alone does not trigger this mode. A deny list
+containing only audited OpenClaw-owned tools can also stay on the normal native
+surface; the harness enforces those denies without disabling unrelated Codex
+capabilities. See [Native tool-policy enforcement](/plugins/sdk-agent-harness#native-tool-policy-enforcement)
+for the generic harness contract and [Codex harness reference](/plugins/codex-harness-reference#restricted-turns)
+for the current Codex rules.
+
+For an ordinary policy-restricted turn, OpenClaw disables Codex native Code
+Mode, removes environment selections, disables and verifies inherited and
+configured MCP servers, disables native hook relays, and filters OpenClaw
+dynamic tools through the effective policy. The bounded workspace `AGENTS.md`
+snapshot still reaches the model as thread-level developer instructions because
+project instructions are context, not tool authority.
+
+**Ring zero** is stronger and separate. It is the host-owned OpenClaw system
+agent used for setup and repair operations. The host activates it with the
+single `openclaw` tool; normal agent config cannot opt a chat into ring zero.
+Ring-zero turns keep only that host-scoped tool, replace ambient Codex
+instructions with host-authored setup instructions, disable native tools and
+MCP servers, and suppress workspace project documents, including the
+`AGENTS.md` developer-instruction carrier.
+
+Other narrow internal modes also suppress project documents: lightweight
+bootstrap turns, message-only source replies, and tool-disabled internal turns.
+They share some isolation settings with policy-restricted turns but are not
+synonyms for ring zero.
+
 ### Project instructions
 
 Codex loads `AGENTS.md` files through native project-document discovery. For
 normal app-server threads, OpenClaw raises Codex's aggregate root-to-working-
 directory budget from the upstream 32 KiB default to a bounded 128 KiB so later
-scoped instructions are not silently clipped. Lightweight and restricted turns
-set the native project-document budget to zero instead.
+scoped instructions are not silently clipped. Ordinary conversation tool-policy
+restrictions preserve that budget because project instructions are context, not
+tool authority. Their isolated native environment cannot read workspace files,
+so OpenClaw supplies the bounded workspace `AGENTS.md` snapshot as thread-level
+developer instructions. Lightweight, ring-zero, message-only, and tool-disabled
+internal turns set the native project-document budget to zero instead.
 
 This byte budget is separate from the character-based workspace bootstrap
 limits configured through `agents.defaults.bootstrapMaxChars` and
diff --git a/extensions/codex/src/app-server/attempt-context.test.ts b/extensions/codex/src/app-server/attempt-context.test.ts
index b40665c8fe0f..69500c6074b9 100644
--- a/extensions/codex/src/app-server/attempt-context.test.ts
+++ b/extensions/codex/src/app-server/attempt-context.test.ts
@@ -141,6 +141,7 @@ describe("Codex app-server attempt context", () => {
       sessionKey: "agent:main:session-1",
       sessionAgentId: "main",
       memoryToolNames: ["memory_search", "memory_get"],
+      ringZeroActive: false,
     });
 
     expect(context.memoryReferenceFiles).toEqual([]);
@@ -181,6 +182,7 @@ describe("Codex app-server attempt context", () => {
         sessionKey: "agent:marketing-agent:session-1",
         sessionAgentId: "marketing-agent",
         memoryToolNames: ["memory_search", "memory_get"],
+        ringZeroActive: false,
         sandboxed: true,
       });
 
@@ -219,6 +221,7 @@ describe("Codex app-server attempt context", () => {
         sessionKey: "agent:main:session-1",
         sessionAgentId: "main",
         memoryToolNames: ["memory_search", "memory_get"],
+        ringZeroActive: false,
       });
 
       expect(context.threadDeveloperInstructions).toContain("Canonical agent instructions");
@@ -241,6 +244,37 @@ describe("Codex app-server attempt context", () => {
     }
   });
 
+  it("keeps ambient workspace instructions out of overlapping ring-zero restrictions", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "codex-ring-zero-workspace-"));
+    const executionDir = await fs.mkdtemp(path.join(os.tmpdir(), "codex-ring-zero-execution-"));
+    await fs.writeFile(path.join(workspaceDir, "AGENTS.md"), "Ambient workspace instructions");
+
+    try {
+      const context = await buildCodexWorkspaceBootstrapContext({
+        params: {
+          sessionId: "session-1",
+          sessionKey: "agent:openclaw:session-1",
+          toolsAllow: ["openclaw"],
+          pluginHarnessToolPolicyRestricted: true,
+          config: { agents: { defaults: { workspace: workspaceDir } } },
+        } as EmbeddedRunAttemptParams,
+        resolvedWorkspace: workspaceDir,
+        executionWorkspace: executionDir,
+        effectiveWorkspace: executionDir,
+        sessionKey: "agent:openclaw:session-1",
+        sessionAgentId: "openclaw",
+        memoryToolNames: [],
+        ringZeroActive: true,
+      });
+
+      expect(context.threadDeveloperInstructions).toBeUndefined();
+      expect(context.threadDeveloperInstructionFiles).toEqual([]);
+    } finally {
+      await fs.rm(workspaceDir, { recursive: true, force: true });
+      await fs.rm(executionDir, { recursive: true, force: true });
+    }
+  });
+
   it("reads and compares thread-bootstrap context-engine projections", () => {
     const projection = readContextEngineThreadBootstrapProjection({
       mode: "thread_bootstrap",
diff --git a/extensions/codex/src/app-server/attempt-context.ts b/extensions/codex/src/app-server/attempt-context.ts
index 58958eded63e..df98201ead7d 100644
--- a/extensions/codex/src/app-server/attempt-context.ts
+++ b/extensions/codex/src/app-server/attempt-context.ts
@@ -26,6 +26,7 @@ import type {
 } from "openclaw/plugin-sdk/session-transcript-runtime";
 import { readNonBlankString as readNonEmptyString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import type { EmbeddedRunAttemptResult } from "./attempt-terminal.js";
+import { isMessageOnlyCodexSourceReply } from "./dynamic-tool-profile.js";
 import type { CodexDynamicToolFunctionSpec, CodexDynamicToolSpec, JsonValue } from "./protocol.js";
 import { flattenCodexDynamicToolFunctions, isJsonObject } from "./protocol.js";
 import type { CodexAppServerThreadBinding } from "./session-binding.js";
@@ -176,6 +177,7 @@ export async function buildCodexWorkspaceBootstrapContext(params: {
   sessionKey: string;
   sessionAgentId: string;
   memoryToolNames: readonly string[];
+  ringZeroActive: boolean;
   sandboxed?: boolean;
 }): Promise<CodexWorkspaceBootstrapContext> {
   try {
@@ -244,8 +246,15 @@ export async function buildCodexWorkspaceBootstrapContext(params: {
       memoryWorkspaceDir: params.effectiveWorkspace,
     });
     const injectOpenClawContext = shouldInjectCodexOpenClawPromptContext(params.params);
+    const restrictedProjectDocNeedsOpenClawCarrier =
+      params.params.pluginHarnessToolPolicyRestricted === true &&
+      !params.params.disableTools &&
+      !isMessageOnlyCodexSourceReply(params.params) &&
+      params.params.bootstrapContextMode !== "lightweight";
     const threadDeveloperInstructionFiles =
-      injectOpenClawContext && inheritsAgentWorkspace
+      injectOpenClawContext &&
+      !params.ringZeroActive &&
+      (inheritsAgentWorkspace || restrictedProjectDocNeedsOpenClawCarrier)
         ? selectCodexWorkspaceAgentProjectInstructionFiles(contextFiles, params.resolvedWorkspace)
         : [];
     const turnScopedDeveloperInstructionFiles = injectOpenClawContext
diff --git a/extensions/codex/src/app-server/run-attempt-context.ts b/extensions/codex/src/app-server/run-attempt-context.ts
index d153858127f7..57858d771653 100644
--- a/extensions/codex/src/app-server/run-attempt-context.ts
+++ b/extensions/codex/src/app-server/run-attempt-context.ts
@@ -4,6 +4,7 @@ import {
   CODEX_APP_SERVER_CONTEXT_ENGINE_HOST,
   embeddedAgentLog,
   getAgentHarnessHookRunner,
+  isHostScopedAgentToolActive,
   resolveContextEngineOwnerPluginId,
   runHarnessContextEngineMaintenance,
 } from "openclaw/plugin-sdk/agent-harness-runtime";
@@ -21,6 +22,7 @@ import {
   resolveCodexContinuityProjectionMaxChars,
   type CodexProjectedContextRange,
 } from "./context-engine-projection.js";
+import { isSystemAgentOnlyCodexDynamicToolAllowlist } from "./dynamic-tool-profile.js";
 import type { CodexAttemptRuntime } from "./run-attempt-runtime.js";
 import { joinPresentSections } from "./run-attempt-state.js";
 import type { CodexAttemptTools } from "./run-attempt-tool-setup.js";
@@ -148,11 +150,14 @@ export async function prepareCodexAttemptContext(
     sessionKey: contextSessionKey,
     sessionAgentId,
     memoryToolNames,
+    ringZeroActive:
+      isHostScopedAgentToolActive("openclaw") &&
+      isSystemAgentOnlyCodexDynamicToolAllowlist(runtimeParams.toolsAllow),
     sandboxed: sandbox?.enabled === true,
   });
   // A thread keeps the bounded agent-workspace snapshot captured at creation.
   // Workspace edits take effect only in the next session.
-  const agentWorkspaceDeveloperInstructions = workspaceBootstrapContext.inheritsAgentWorkspace
+  const agentWorkspaceDeveloperInstructions = workspaceBootstrapContext.threadDeveloperInstructions
     ? (connection.mutable.startupBinding?.agentWorkspaceDeveloperInstructions ??
       workspaceBootstrapContext.threadDeveloperInstructions)
     : undefined;
diff --git a/extensions/codex/src/app-server/run-attempt.test.ts b/extensions/codex/src/app-server/run-attempt.test.ts
index 1dde07c9ff37..fcc135ee997b 100644
--- a/extensions/codex/src/app-server/run-attempt.test.ts
+++ b/extensions/codex/src/app-server/run-attempt.test.ts
@@ -429,6 +429,7 @@ async function buildCodexTurnContextForTest(
     sessionKey: params.sessionKey ?? params.sessionId,
     sessionAgentId,
     memoryToolNames,
+    ringZeroActive: false,
   });
   const threadDeveloperInstructions = testing.buildDeveloperInstructions(params, { dynamicTools });
   const openClawPromptContext = buildCodexOpenClawPromptContext({
@@ -2415,6 +2416,10 @@ describe("runCodexAppServerAttempt", () => {
       deny: ["exec", "process", "write", "edit"],
     };
     params.pluginHarnessToolPolicyRestricted = true;
+    const agentsGuidance = "Restricted turns keep workspace AGENTS guidance.";
+    await fs.mkdir(params.workspaceDir, { recursive: true });
+    await fs.writeFile(path.join(params.workspaceDir, "AGENTS.md"), agentsGuidance);
+    setAgentWorkspaceForTest(params, params.workspaceDir);
     const onAgentEvent = vi.fn();
     params.onAgentEvent = onAgentEvent;
     const harness = createStartedThreadHarness(async (method) => {
@@ -2437,6 +2442,7 @@ describe("runCodexAppServerAttempt", () => {
       | {
           dynamicTools?: CodexDynamicToolSpec[];
           environments?: unknown[];
+          developerInstructions?: string;
           config?: Record<string, unknown>;
         }
       | undefined;
@@ -2445,6 +2451,8 @@ describe("runCodexAppServerAttempt", () => {
     );
 
     expect(startParams?.environments).toEqual([]);
+    expect(startParams?.config?.project_doc_max_bytes).toBe(131_072);
+    expect(startParams?.developerInstructions?.split(agentsGuidance)).toHaveLength(2);
     expect(startParams?.config?.["tools.update_plan.enabled"]).toBe(false);
     expect(dynamicToolNames.toSorted()).toEqual(["apply_patch", "progress_card", "read"]);
     const progressCardSpec = flattenSpecsWithNamespace(startParams?.dynamicTools ?? []).find(
diff --git a/extensions/codex/src/app-server/session-binding.ts b/extensions/codex/src/app-server/session-binding.ts
index d472e9ba2089..be9bee34575b 100644
--- a/extensions/codex/src/app-server/session-binding.ts
+++ b/extensions/codex/src/app-server/session-binding.ts
@@ -210,8 +210,8 @@ const threadBindingSchema = z
     connectionScope: z.literal("supervision").optional(),
     supervisionSourceThreadId: z.string().trim().min(1).optional(),
     authProfileId: optionalStringSchema,
-    // Freeze external-cwd AGENTS.md at thread creation; bootstrap refreshes must
-    // not mutate the inherited policy of a resumed native session.
+    // Freeze OpenClaw-carried AGENTS.md at thread creation; bootstrap refreshes
+    // must not mutate the inherited policy of a resumed native session.
     agentWorkspaceDeveloperInstructions: optionalNonBlankStringSchema,
     model: optionalStringSchema,
     // Codex App Server owns selection for supervised and adopted threads. Keep
diff --git a/extensions/codex/src/app-server/thread-lifecycle.test.ts b/extensions/codex/src/app-server/thread-lifecycle.test.ts
index 0cd57bd4d847..19b212d2c2d9 100644
--- a/extensions/codex/src/app-server/thread-lifecycle.test.ts
+++ b/extensions/codex/src/app-server/thread-lifecycle.test.ts
@@ -355,11 +355,14 @@ describe("Codex ring-zero thread config", () => {
   it("applies the restriction to both thread start and resume", () => {
     const params = createAttemptParams({ provider: "openai" });
     params.toolsAllow = ["openclaw"];
+    params.pluginHarnessToolPolicyRestricted = true;
     const appServer = createAppServerOptions() as never;
+    const developerInstructions = "Host-authored ring-zero instructions.";
     const start = buildThreadStartParams(params, {
       appServer,
       cwd: "/repo",
       dynamicTools: [],
+      developerInstructions,
       hostSystemAgentActive: true,
       nativeCodeModeEnabled: false,
       config: { project_doc_max_bytes: 64_000 },
@@ -367,6 +370,7 @@ describe("Codex ring-zero thread config", () => {
     const resume = buildThreadResumeParams(params, {
       appServer,
       dynamicTools: [],
+      developerInstructions,
       hostSystemAgentActive: true,
       nativeCodeModeEnabled: false,
       threadId: "thread-1",
@@ -375,6 +379,8 @@ describe("Codex ring-zero thread config", () => {
 
     expect(start.environments).toEqual([]);
     expect(start.baseInstructions).toBe("");
+    expect(start.developerInstructions).toBe(developerInstructions);
+    expect(resume.developerInstructions).toBe(developerInstructions);
     for (const config of [start.config, resume.config]) {
       expect(config?.["agents.enabled"]).toBe(false);
       expect(config?.["tools.experimental_request_user_input.enabled"]).toBe(false);
@@ -402,6 +408,47 @@ describe("Codex ring-zero thread config", () => {
     expect(normal.baseInstructions).toBeUndefined();
     expect(normal.config?.["features.goals"]).toBe(false);
   });
+
+  it("preserves project documents for ordinary policy-restricted turns", () => {
+    const params = createAttemptParams({ provider: "openai" });
+    params.pluginHarnessToolPolicyRestricted = true;
+    const appServer = createAppServerOptions() as never;
+    const start = buildThreadStartParams(params, {
+      appServer,
+      cwd: "/repo",
+      dynamicTools: [],
+      hostSystemAgentActive: false,
+      nativeCodeModeEnabled: false,
+    });
+    const resume = buildThreadResumeParams(params, {
+      appServer,
+      dynamicTools: [],
+      hostSystemAgentActive: false,
+      nativeCodeModeEnabled: false,
+      threadId: "thread-1",
+      config: { project_doc_max_bytes: 64_000 },
+    });
+
+    expect(start.config?.project_doc_max_bytes).toBe(131_072);
+    expect(resume.config?.project_doc_max_bytes).toBe(64_000);
+    for (const threadConfig of [start.config, resume.config]) {
+      expect(threadConfig?.["features.multi_agent"]).toBe(false);
+      expect(threadConfig?.["orchestrator.mcp.enabled"]).toBe(false);
+    }
+
+    const toolsDisabled = createAttemptParams({ provider: "openai" });
+    toolsDisabled.disableTools = true;
+    toolsDisabled.pluginHarnessToolPolicyRestricted = true;
+    const disabled = buildThreadStartParams(toolsDisabled, {
+      appServer,
+      cwd: "/repo",
+      dynamicTools: [],
+      hostSystemAgentActive: false,
+      nativeCodeModeEnabled: false,
+      config: { project_doc_max_bytes: 64_000 },
+    });
+    expect(disabled.config?.project_doc_max_bytes).toBe(0);
+  });
 });
 
 describe("Codex delegation capability", () => {
@@ -3620,6 +3667,7 @@ describe("Codex app-server supervised branch lifecycle", () => {
         | { config?: Record<string, unknown> }
         | undefined;
       expect(threadRequest?.config).toMatchObject({
+        project_doc_max_bytes: 0,
         mcp_servers: {
           inherited: { enabled: false },
           "request-only": { enabled: false },
diff --git a/extensions/codex/src/app-server/thread-requests.ts b/extensions/codex/src/app-server/thread-requests.ts
index 05d5597009bc..a89b5b6ff2a3 100644
--- a/extensions/codex/src/app-server/thread-requests.ts
+++ b/extensions/codex/src/app-server/thread-requests.ts
@@ -56,7 +56,7 @@ const CODEX_CODE_MODE_DISABLED_THREAD_CONFIG: JsonObject = {
   "features.code_mode_only": false,
 };
 
-const CODEX_LIGHTWEIGHT_CONTEXT_THREAD_CONFIG: JsonObject = {
+const CODEX_NO_PROJECT_DOCS_CONFIG: JsonObject = {
   project_doc_max_bytes: 0,
 };
 
@@ -126,7 +126,6 @@ const CODEX_RING_ZERO_THREAD_CONFIG: JsonObject = {
     SubagentStop: [],
     Stop: [],
   },
-  project_doc_max_bytes: 0,
   notify: [],
   web_search: "disabled",
 };
@@ -430,6 +429,10 @@ export function buildCodexRuntimeThreadConfigForRun(
   const messageOnlySourceReply = isMessageOnlyCodexSourceReply(params);
   const restrictedToolSurface =
     ringZeroActive || messageOnlySourceReply || params.pluginHarnessToolPolicyRestricted === true;
+  const restrictedTurnDisablesProjectDocs =
+    ringZeroActive ||
+    messageOnlySourceReply ||
+    (params.pluginHarnessToolPolicyRestricted && params.disableTools);
   const configMcpServers = config?.mcp_servers;
   if (restrictedToolSurface && configMcpServers !== undefined && !isJsonObject(configMcpServers)) {
     throw new Error("Codex restricted tool surface received invalid thread mcp_servers config");
@@ -469,23 +472,21 @@ export function buildCodexRuntimeThreadConfigForRun(
         ? CODEX_DELEGATION_DISABLED_THREAD_CONFIG
         : undefined,
       messageOnlySourceReply || params.pluginHarnessToolPolicyRestricted === true
-        ? buildCodexRestrictedToolThreadConfigPatch(restrictedToolSurfaceMcpServerNames)
+        ? buildRestrictedToolConfigPatch(restrictedToolSurfaceMcpServerNames)
         : buildCodexRingZeroThreadConfigPatch(
             params,
             options.hostSystemAgentActive,
             restrictedToolSurfaceMcpServerNames,
           ),
+      restrictedTurnDisablesProjectDocs ? CODEX_NO_PROJECT_DOCS_CONFIG : undefined,
       params.authoredContextTokenCap === undefined
         ? undefined
         : { model_context_window: params.authoredContextTokenCap },
     ) ?? baseConfig;
-  const contextConfig =
-    params.bootstrapContextMode !== "lightweight"
-      ? runtimeConfig
-      : (mergeCodexThreadConfigs(runtimeConfig, CODEX_LIGHTWEIGHT_CONTEXT_THREAD_CONFIG) ?? {
-          ...runtimeConfig,
-          ...CODEX_LIGHTWEIGHT_CONTEXT_THREAD_CONFIG,
-        });
+  const contextConfig = {
+    ...runtimeConfig,
+    ...(params.bootstrapContextMode === "lightweight" ? CODEX_NO_PROJECT_DOCS_CONFIG : {}),
+  };
   return applyCodexManagedShellEnvironment(
     contextConfig,
     options.shellEnvironment,
@@ -501,15 +502,16 @@ export function buildCodexRingZeroThreadConfigPatch(
   if (!hostSystemAgentActive || !isSystemAgentOnlyCodexDynamicToolAllowlist(params.toolsAllow)) {
     return undefined;
   }
-  return buildCodexRestrictedToolThreadConfigPatch(inheritedMcpServerNames);
+  return {
+    ...buildRestrictedToolConfigPatch(inheritedMcpServerNames),
+    ...CODEX_NO_PROJECT_DOCS_CONFIG,
+  };
 }
 
-function buildCodexRestrictedToolThreadConfigPatch(
-  inheritedMcpServerNames: readonly string[],
-): JsonObject {
-  // Restricted turns already send environments: [] and disable native code
-  // mode. Remove every other configurable Codex-owned source so
-  // native delegation, installed MCP tools, and utilities cannot escape the cap.
+function buildRestrictedToolConfigPatch(inheritedMcpServerNames: readonly string[]): JsonObject {
+  // Restricted turns already send environments: [] and disable native code mode.
+  // Remove Codex-owned tool sources here; project-document suppression belongs to
+  // ring-zero, message-only, and tool-disabled context policy at the caller.
   const mcpServers = Object.fromEntries(
     [...new Set(inheritedMcpServerNames)].toSorted().map((name) => [name, { enabled: false }]),
   );

From 081810c9be95aea705ca0dc79b5b95015cbf6f6e Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Fri, 21 Aug 2026 10:00:52 -0700
Subject: [PATCH 036/124] refactor(gateway): flatten HTTP request stages
 (#127264)

---
 src/gateway/server-http.ts | 120 +++++++++++++++++--------------------
 1 file changed, 55 insertions(+), 65 deletions(-)

diff --git a/src/gateway/server-http.ts b/src/gateway/server-http.ts
index 56fef2a249c2..a8e98726cdb5 100644
--- a/src/gateway/server-http.ts
+++ b/src/gateway/server-http.ts
@@ -137,15 +137,13 @@ function isWebSocketUpgradeRequest(req: IncomingMessage): boolean {
   );
 }
 
-type GatewayHttpRequestStage = {
-  run: () => Promise<boolean> | boolean;
-};
+type GatewayHttpRequestStage = () => Promise<boolean> | boolean;
 
 async function runGatewayHttpRequestStages(
   stages: readonly GatewayHttpRequestStage[],
 ): Promise<boolean> {
   for (const stage of stages) {
-    if (await stage.run()) {
+    if (await stage()) {
       return true;
     }
   }
@@ -335,34 +333,30 @@ export function createGatewayHttpServer(opts: {
         return true;
       };
       const requestStages: GatewayHttpRequestStage[] = [
-        {
-          run: () =>
-            handleGatewayProbeRequest(
-              req,
-              res,
-              scopedRequestPath,
-              resolvedAuthValue,
-              trustedProxies,
-              allowRealIpFallback,
-              rateLimiter,
-              getReadiness,
-              getStartup,
-            ),
-        },
+        () =>
+          handleGatewayProbeRequest(
+            req,
+            res,
+            scopedRequestPath,
+            resolvedAuthValue,
+            trustedProxies,
+            allowRealIpFallback,
+            rateLimiter,
+            getReadiness,
+            getStartup,
+          ),
       ];
       const addRequestStage = (
         enabled: boolean,
-        run: GatewayHttpRequestStage["run"],
+        stage: GatewayHttpRequestStage,
         admitted = false,
       ) => {
         if (enabled) {
-          requestStages.push({
-            run: admitted ? () => runWithGatewayHttpWorkAdmission(res, run) : run,
-          });
+          requestStages.push(admitted ? () => runWithGatewayHttpWorkAdmission(res, stage) : stage);
         }
       };
-      const addAdmittedStage = (enabled: boolean, run: GatewayHttpRequestStage["run"]) =>
-        addRequestStage(enabled, run, true);
+      const addAdmittedStage = (enabled: boolean, stage: GatewayHttpRequestStage) =>
+        addRequestStage(enabled, stage, true);
 
       const workerGatewayRoute = classifyWorkerGatewayPath(scopedRequestPath);
       addRequestStage(workerGatewayRoute !== "outside", () => {
@@ -519,8 +513,8 @@ export function createGatewayHttpServer(opts: {
         configSnapshot.mcp?.apps?.enabled === true &&
         (mcpAppRoute === "shell" || mcpAppRoute === "view")
       ) {
-        requestStages.push({
-          run: async () =>
+        requestStages.push(
+          async () =>
             await runWithGatewayHttpWorkAdmission(res, async () => {
               const standalone = await getMcpAppStandaloneModule();
               return await standalone.handleMcpAppStandaloneHttpRequest(req, res, {
@@ -528,7 +522,7 @@ export function createGatewayHttpServer(opts: {
                 sandboxOrigin: configSnapshot.mcp?.apps?.sandboxOrigin,
               });
             }),
-        });
+        );
       }
       // Core and recovery routes run first, then plugin routes, then read-only Control UI
       // surfaces. Non-GET requests the SPA does not claim reach the startup 503 before final 404.
@@ -538,46 +532,42 @@ export function createGatewayHttpServer(opts: {
         let pluginRequestOperatorScopes: string[] | undefined;
         // Auth and dispatch stay separate so authorized context reaches the handler.
         requestStages.push(
-          {
-            run: async () => {
-              if (
-                !(shouldEnforcePluginGatewayAuth ?? shouldEnforceDefaultPluginGatewayAuth)(
-                  pluginPathContext,
-                ) ||
-                (await getCachedPluginGatewayAuthBypassPaths(configSnapshot)).has(scopedRequestPath)
-              ) {
-                return false;
-              }
-              // Bypass paths come only from activated channel plugins; every other protected
-              // route must authorize before runtime scopes are derived.
-              const { authorizePluginGatewayHttpRequestOrReply } = await getHttpAuthUtilsModule();
-              const { resolvePluginRouteRuntimeOperatorScopes } =
-                await getPluginRouteRuntimeScopesModule();
-              const authResult = await authorizePluginGatewayHttpRequestOrReply({
-                req,
-                res,
-                ...routeAuth,
-                requestPath: scopedRequestPath,
-                resolveOperatorScopes: resolvePluginRouteRuntimeOperatorScopes,
-              });
-              if (!authResult) {
-                return true;
-              }
-              pluginGatewayAuthSatisfied = true;
-              pluginGatewayRequestAuth = authResult.requestAuth;
-              pluginRequestOperatorScopes = authResult.operatorScopes;
+          async () => {
+            if (
+              !(shouldEnforcePluginGatewayAuth ?? shouldEnforceDefaultPluginGatewayAuth)(
+                pluginPathContext,
+              ) ||
+              (await getCachedPluginGatewayAuthBypassPaths(configSnapshot)).has(scopedRequestPath)
+            ) {
               return false;
-            },
-          },
-          {
-            run: () =>
-              handlePluginRequest(req, res, pluginPathContext, {
-                gatewayAuthSatisfied: pluginGatewayAuthSatisfied,
-                gatewayRequestAuth: pluginGatewayRequestAuth,
-                gatewayRequestOperatorScopes: pluginRequestOperatorScopes,
-                gatewayRequestClientIp: requestClientIp,
-              }),
+            }
+            // Bypass paths come only from activated channel plugins; every other protected
+            // route must authorize before runtime scopes are derived.
+            const { authorizePluginGatewayHttpRequestOrReply } = await getHttpAuthUtilsModule();
+            const { resolvePluginRouteRuntimeOperatorScopes } =
+              await getPluginRouteRuntimeScopesModule();
+            const authResult = await authorizePluginGatewayHttpRequestOrReply({
+              req,
+              res,
+              ...routeAuth,
+              requestPath: scopedRequestPath,
+              resolveOperatorScopes: resolvePluginRouteRuntimeOperatorScopes,
+            });
+            if (!authResult) {
+              return true;
+            }
+            pluginGatewayAuthSatisfied = true;
+            pluginGatewayRequestAuth = authResult.requestAuth;
+            pluginRequestOperatorScopes = authResult.operatorScopes;
+            return false;
           },
+          () =>
+            handlePluginRequest(req, res, pluginPathContext, {
+              gatewayAuthSatisfied: pluginGatewayAuthSatisfied,
+              gatewayRequestAuth: pluginGatewayRequestAuth,
+              gatewayRequestOperatorScopes: pluginRequestOperatorScopes,
+              gatewayRequestClientIp: requestClientIp,
+            }),
         );
       }
 

From 40151953b0abefabc6fe43fbe9b6f8ab5ee7f5b5 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 10:10:18 -0700
Subject: [PATCH 037/124] test(cli): use shared temp dir tracker (#127286)

---
 src/cli/update-cli.test.ts | 76 +++++++++++++++++---------------------
 1 file changed, 34 insertions(+), 42 deletions(-)

diff --git a/src/cli/update-cli.test.ts b/src/cli/update-cli.test.ts
index 76787f9267ec..598c9738aa72 100644
--- a/src/cli/update-cli.test.ts
+++ b/src/cli/update-cli.test.ts
@@ -8,6 +8,7 @@ import { expectDefined } from "@openclaw/normalization-core";
 import { Command } from "commander";
 import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { writePackageDistInventory } from "../../scripts/lib/package-dist-inventory.ts";
+import { useAutoCleanupTempDirTracker } from "../../test/helpers/temp-dir.js";
 import type { OpenClawConfig, ConfigFileSnapshot } from "../config/types.openclaw.js";
 import type { PluginInstallRecord } from "../config/types.plugins.js";
 import { GATEWAY_SERVICE_RUNTIME_PID_ENV } from "../daemon/constants.js";
@@ -545,6 +546,7 @@ describe("update-cli", () => {
     fsSync.mkdtempSync(path.join(os.tmpdir(), "openclaw-update-tests-")),
   );
   let fixtureCount = 0;
+  const tempDirs = useAutoCleanupTempDirTracker(afterEach);
   const tempDirsToCleanup = new Set<string>();
 
   const createCaseDir = (prefix: string) => {
@@ -553,12 +555,6 @@ describe("update-cli", () => {
     return dir;
   };
 
-  const createTrackedTempDir = async (prefix: string) => {
-    const dir = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), prefix)));
-    tempDirsToCleanup.add(dir);
-    return dir;
-  };
-
   const baseConfig = {} as OpenClawConfig;
   const baseSnapshot: ConfigFileSnapshot = {
     path: "/tmp/openclaw-config.json",
@@ -1314,8 +1310,8 @@ describe("update-cli", () => {
     options: Parameters<typeof updateCommand>[0];
     beforeUpdate?: () => void | Promise<void>;
   }) => {
-    const stateDir = await createTrackedTempDir("openclaw-update-sentinel-state-");
-    const metaDir = await createTrackedTempDir("openclaw-update-sentinel-meta-");
+    const stateDir = tempDirs.make("openclaw-update-sentinel-state-");
+    const metaDir = tempDirs.make("openclaw-update-sentinel-meta-");
     const metaPath = path.join(metaDir, "meta.json");
     await fs.writeFile(metaPath, JSON.stringify({ version: 1, meta: params.meta }));
     await params.beforeUpdate?.();
@@ -1758,7 +1754,7 @@ describe("update-cli", () => {
   it("keeps foreign-service updates in the caller profile", async () => {
     const personalState = path.join(fixtureRoot, "personal-profile");
     const { root, entrypoints } = setupUpdatedRootRefresh();
-    const foreignRoot = await createTrackedTempDir("openclaw-update-foreign-profile-");
+    const foreignRoot = tempDirs.make("openclaw-update-foreign-profile-");
     const foreignEntrypoint = path.join(foreignRoot, "dist", "index.js");
     await fs.mkdir(path.dirname(foreignEntrypoint), { recursive: true });
     await fs.writeFile(
@@ -4473,7 +4469,7 @@ describe("update-cli", () => {
   });
 
   it("stops package post-update work when staged npm install verification fails", async () => {
-    const tempDir = await createTrackedTempDir("openclaw-update-staged-fail-");
+    const tempDir = tempDirs.make("openclaw-update-staged-fail-");
     const prefix = path.join(tempDir, "prefix");
     const nodeModules = path.join(prefix, "lib", "node_modules");
     const { pkgRoot } = await setupInstalledPackageAtNodeModules(nodeModules, "2026.4.20");
@@ -4524,7 +4520,7 @@ describe("update-cli", () => {
   });
 
   it("runs old package doctors without fix mode when service ownership is unknown", async () => {
-    const tempDir = await createTrackedTempDir("openclaw-update-package-");
+    const tempDir = tempDirs.make("openclaw-update-package-");
     const { nodeModules, pkgRoot, entryPath } = await setupInstalledPackageRoot(tempDir);
     primeServiceCommand(["openclaw-wrapper", "gateway", "run"]);
     serviceLoaded.mockResolvedValue(true);
@@ -4568,7 +4564,7 @@ describe("update-cli", () => {
   });
 
   it("continues package post-core work for explicit post-update doctor advisories", async () => {
-    const tempDir = await createTrackedTempDir("openclaw-update-package-doctor-warning-");
+    const tempDir = tempDirs.make("openclaw-update-package-doctor-warning-");
     const { nodeModules, entryPath } = await setupInstalledPackageRoot(tempDir);
     primeNpmChannelTag("latest", "2026.4.21");
     mockFileBackedPathExists();
@@ -4637,7 +4633,7 @@ describe("update-cli", () => {
   });
 
   it("fails package updates when the post-update doctor is killed after verification", async () => {
-    const tempDir = await createTrackedTempDir("openclaw-update-package-doctor-timeout-");
+    const tempDir = tempDirs.make("openclaw-update-package-doctor-timeout-");
     const { nodeModules, entryPath } = await setupInstalledPackageRoot(tempDir);
     primeNpmChannelTag("latest", "2026.4.21");
     mockFileBackedPathExists();
@@ -4678,7 +4674,7 @@ describe("update-cli", () => {
   });
 
   it("runs package post-update doctor from the verified package root after a staged swap", async () => {
-    const tempDir = await createTrackedTempDir("openclaw-update-staged-doctor-");
+    const tempDir = tempDirs.make("openclaw-update-staged-doctor-");
     const { nodeModules, pkgRoot, entryPath } = await setupInstalledPackageAtNodeModules(
       path.join(tempDir, "lib", "node_modules"),
     );
@@ -4741,7 +4737,7 @@ describe("update-cli", () => {
     const processOffSpy = vi.spyOn(process, "off");
     suspendScheduledTaskAutoStartForUpdate.mockResolvedValue(true);
     resumeScheduledTaskAutoStartAfterUpdate.mockResolvedValue(true);
-    const tempDir = await createTrackedTempDir("openclaw-update-stop-service-");
+    const tempDir = tempDirs.make("openclaw-update-stop-service-");
     const { nodeModules } = await setupInstalledPackageRoot(tempDir);
     mockRunningManagedGateway();
     mockFileBackedPathExists();
@@ -4815,7 +4811,7 @@ describe("update-cli", () => {
     "quiesces a stopped loaded managed gateway on $platform before package replacement",
     async ({ platform, handoff }) => {
       const platformSpy = vi.spyOn(process, "platform", "get").mockReturnValue(platform);
-      const tempDir = await createTrackedTempDir(`openclaw-update-stopped-loaded-${platform}-`);
+      const tempDir = tempDirs.make(`openclaw-update-stopped-loaded-${platform}-`);
       const { nodeModules, entryPath } = await setupInstalledPackageRoot(tempDir);
       primeServiceCommand(["node", entryPath, "gateway", "run"], {
         OPENCLAW_SERVICE_MARKER: "openclaw",
@@ -4880,7 +4876,7 @@ describe("update-cli", () => {
     { name: "an ordinary stopped Scheduled Task", platform: "win32" as const, loaded: true },
   ])("leaves $name stopped during package replacement", async ({ platform, loaded }) => {
     const platformSpy = vi.spyOn(process, "platform", "get").mockReturnValue(platform);
-    const tempDir = await createTrackedTempDir(`openclaw-update-stopped-${platform}-`);
+    const tempDir = tempDirs.make(`openclaw-update-stopped-${platform}-`);
     const { nodeModules, entryPath } = await setupInstalledPackageRoot(tempDir);
     primeServiceCommand(["node", entryPath, "gateway", "run"]);
     serviceLoaded.mockResolvedValue(loaded);
@@ -4903,7 +4899,7 @@ describe("update-cli", () => {
 
   it("restarts a quiesced stopped LaunchAgent after package replacement fails", async () => {
     const platformSpy = vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
-    const tempDir = await createTrackedTempDir("openclaw-update-stopped-launchagent-failure-");
+    const tempDir = tempDirs.make("openclaw-update-stopped-launchagent-failure-");
     const { nodeModules, entryPath } = await setupInstalledPackageRoot(tempDir);
     primeServiceCommand(["node", entryPath, "gateway", "run"]);
     serviceLoaded.mockResolvedValue(true);
@@ -4943,7 +4939,7 @@ describe("update-cli", () => {
 
   it("leaves a disabled stopped LaunchAgent disabled when package replacement fails", async () => {
     const platformSpy = vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
-    const tempDir = await createTrackedTempDir("openclaw-update-disabled-launchagent-failure-");
+    const tempDir = tempDirs.make("openclaw-update-disabled-launchagent-failure-");
     const { nodeModules, entryPath } = await setupInstalledPackageRoot(tempDir);
     primeServiceCommand(["node", entryPath, "gateway", "run"]);
     serviceLoaded.mockResolvedValue(true);
@@ -4974,7 +4970,7 @@ describe("update-cli", () => {
 
   it("does not inspect or mutate a Windows host service from an isolated install", async () => {
     const platformSpy = vi.spyOn(process, "platform", "get").mockReturnValue("win32");
-    const tempDir = await createTrackedTempDir("openclaw-update-isolated-service-");
+    const tempDir = tempDirs.make("openclaw-update-isolated-service-");
     const { nodeModules } = await setupInstalledPackageRoot(tempDir);
     mockRunningManagedGateway();
     mockFileBackedPathExists();
@@ -5016,7 +5012,7 @@ describe("update-cli", () => {
     "does not reuse a conflicting $envKey selector from the managed service on $platform",
     async ({ platform, envKey, value }) => {
       const platformSpy = vi.spyOn(process, "platform", "get").mockReturnValue(platform);
-      const tempDir = await createTrackedTempDir(`openclaw-update-${platform}-selector-`);
+      const tempDir = tempDirs.make(`openclaw-update-${platform}-selector-`);
       const home = path.join(tempDir, "home");
       const stateDir = path.join(home, ".openclaw-work");
       const { nodeModules } = await setupInstalledPackageRoot(tempDir);
@@ -5303,7 +5299,7 @@ describe("update-cli", () => {
 
   it("stops a managed gateway rooted at the git checkout when switching package installs to dev", async () => {
     const packageRoot = createCaseDir("openclaw-update-package-root");
-    const gitRoot = await createTrackedTempDir("openclaw-update-git-service-root-");
+    const gitRoot = tempDirs.make("openclaw-update-git-service-root-");
     const serviceEntrypoint = path.join(gitRoot, "dist", "index.js");
     await fs.mkdir(path.join(gitRoot, ".git"), { recursive: true });
     await fs.mkdir(path.dirname(serviceEntrypoint), { recursive: true });
@@ -5336,9 +5332,9 @@ describe("update-cli", () => {
   });
 
   it("stops a managed gateway rooted at the package install when switching package installs to dev", async () => {
-    const packageRoot = await createTrackedTempDir("openclaw-update-package-service-root-");
+    const packageRoot = tempDirs.make("openclaw-update-package-service-root-");
     const packageEntrypoint = path.join(packageRoot, "dist", "index.js");
-    const gitRoot = await createTrackedTempDir("openclaw-update-git-service-root-");
+    const gitRoot = tempDirs.make("openclaw-update-git-service-root-");
     await fs.mkdir(path.join(gitRoot, ".git"), { recursive: true });
     await fs.mkdir(path.dirname(packageEntrypoint), { recursive: true });
     await fs.writeFile(
@@ -5377,7 +5373,7 @@ describe("update-cli", () => {
   it.runIf(process.platform !== "win32")(
     "continues package-to-Git updates from the published checkout after its alias is retargeted",
     async () => {
-      const root = await createTrackedTempDir("openclaw-update-git-alias-");
+      const root = tempDirs.make("openclaw-update-git-alias-");
       const nodeModules = path.join(root, "package", "node_modules");
       const packageRoot = path.join(nodeModules, "openclaw");
       const targetRoot = path.join(root, "checkout-target");
@@ -5427,7 +5423,7 @@ describe("update-cli", () => {
   );
 
   it("preserves the package and shim when package-to-Git staged activation fails", async () => {
-    const root = await createTrackedTempDir("openclaw-update-package-to-git-fail-");
+    const root = tempDirs.make("openclaw-update-package-to-git-fail-");
     const prefix = path.join(root, "prefix");
     const nodeModules = path.join(prefix, "lib", "node_modules");
     const packageRoot = path.join(nodeModules, "openclaw");
@@ -5481,7 +5477,7 @@ describe("update-cli", () => {
   });
 
   it("does not stop or restart a managed gateway owned by another git checkout", async () => {
-    const otherRoot = await createTrackedTempDir("openclaw-update-other-service-root-");
+    const otherRoot = tempDirs.make("openclaw-update-other-service-root-");
     const otherEntrypoint = path.join(otherRoot, "dist", "index.js");
     await fs.mkdir(path.dirname(otherEntrypoint), { recursive: true });
     await fs.writeFile(
@@ -5548,7 +5544,7 @@ describe("update-cli", () => {
   });
 
   it("keeps managed service stop output off stdout during json package updates", async () => {
-    const tempDir = await createTrackedTempDir("openclaw-update-json-stop-service-");
+    const tempDir = tempDirs.make("openclaw-update-json-stop-service-");
     const { nodeModules } = await setupInstalledPackageRoot(tempDir);
     const stdoutWrite = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
     mockRunningManagedGateway();
@@ -5571,7 +5567,7 @@ describe("update-cli", () => {
   });
 
   it("disarms legacy launchd updater jobs before stopping the gateway", async () => {
-    const tempDir = await createTrackedTempDir("openclaw-update-launchd-loop-");
+    const tempDir = tempDirs.make("openclaw-update-launchd-loop-");
     const { nodeModules } = await setupInstalledPackageRoot(tempDir);
     mockRunningManagedGateway();
     launchdUpdateCleanupMocks.disableCurrentOpenClawUpdateLaunchdJob.mockResolvedValue(true);
@@ -5589,7 +5585,7 @@ describe("update-cli", () => {
   });
 
   it("refreshes package installs even when the current version already matches the target", async () => {
-    const tempDir = await createTrackedTempDir("openclaw-update-current-");
+    const tempDir = tempDirs.make("openclaw-update-current-");
     const { nodeModules, pkgRoot, entryPath } = await setupInstalledPackageRoot(
       tempDir,
       "2026.4.23",
@@ -5624,7 +5620,7 @@ describe("update-cli", () => {
   });
 
   it("retries package updates without optional deps when npm global update fails", async () => {
-    const tempDir = await createTrackedTempDir("openclaw-update-optional-");
+    const tempDir = tempDirs.make("openclaw-update-optional-");
     const nodeModules = path.join(tempDir, "node_modules");
     const pkgRoot = path.join(nodeModules, "openclaw");
     mockPackageInstallStatus(pkgRoot);
@@ -5873,7 +5869,7 @@ describe("update-cli", () => {
 
   it("warns when a package update targets a managed service root outside the shell root", async () => {
     const shellRoot = createCaseDir("openclaw-shell-root");
-    const serviceRoot = await createTrackedTempDir("openclaw-service-root-");
+    const serviceRoot = tempDirs.make("openclaw-service-root-");
     const serviceNode = path.join(path.dirname(serviceRoot), "bin", "node");
     await fs.mkdir(path.join(serviceRoot, "dist"), { recursive: true });
     await fs.writeFile(
@@ -5897,7 +5893,7 @@ describe("update-cli", () => {
 
   it("blocks a stale managed service Node before a no-restart package update", async () => {
     const shellRoot = createCaseDir("openclaw-shell-root");
-    const serviceRoot = await createTrackedTempDir("openclaw-service-root-");
+    const serviceRoot = tempDirs.make("openclaw-service-root-");
     const serviceNode = path.join(path.dirname(serviceRoot), "bin", "node");
     await fs.mkdir(path.join(serviceRoot, "dist"), { recursive: true });
     await fs.mkdir(path.dirname(serviceNode), { recursive: true });
@@ -5938,7 +5934,7 @@ describe("update-cli", () => {
 
   it("runs managed service package follow-up commands with the service Node", async () => {
     const shellRoot = createCaseDir("openclaw-shell-root");
-    const servicePrefix = await createTrackedTempDir("openclaw-service-prefix-");
+    const servicePrefix = tempDirs.make("openclaw-service-prefix-");
     const nodeModules = path.join(servicePrefix, "lib", "node_modules");
     const serviceRoot = path.join(nodeModules, "openclaw");
     const serviceNode = path.join(servicePrefix, "bin", "node");
@@ -6031,7 +6027,7 @@ describe("update-cli", () => {
   });
 
   it("refreshes the managed service to current Node when its baked Node cannot run the target", async () => {
-    const servicePrefix = await createTrackedTempDir("openclaw-service-prefix-");
+    const servicePrefix = tempDirs.make("openclaw-service-prefix-");
     const nodeModules = path.join(servicePrefix, "lib", "node_modules");
     const root = path.join(nodeModules, "openclaw");
     const serviceNode = path.join(servicePrefix, "bin", "node");
@@ -6112,7 +6108,7 @@ describe("update-cli", () => {
   });
 
   it("pins package install to the service root when nodes differ and no owning npm exists at the prefix", async () => {
-    const servicePrefix = await createTrackedTempDir("openclaw-no-npm-prefix-");
+    const servicePrefix = tempDirs.make("openclaw-no-npm-prefix-");
     const nodeModules = path.join(servicePrefix, "lib", "node_modules");
     const root = path.join(nodeModules, "openclaw");
     const serviceNode = path.join(servicePrefix, "bin", "node");
@@ -6136,11 +6132,7 @@ describe("update-cli", () => {
     primeNpmChannelTag("latest", "2026.5.20");
     mockFileBackedPathExists();
     // The PATH npm returns a DIFFERENT global root (simulates Node-B's npm).
-    const nodeBGlobalRoot = path.join(
-      await createTrackedTempDir("node-b-global-"),
-      "lib",
-      "node_modules",
-    );
+    const nodeBGlobalRoot = path.join(tempDirs.make("node-b-global-"), "lib", "node_modules");
     await fs.mkdir(nodeBGlobalRoot, { recursive: true });
     vi.mocked(runCommandWithTimeout).mockImplementation(async (argv) => {
       if (Array.isArray(argv) && argv[0] === serviceNode && argv[1] === "--version") {
@@ -8036,7 +8028,7 @@ describe("update-cli", () => {
   });
 
   it("updateWizardCommand offers dev checkout and forwards selections", async () => {
-    const root = await createTrackedTempDir("openclaw-update-wizard-");
+    const root = tempDirs.make("openclaw-update-wizard-");
     const tempDir = path.join(root, "openclaw");
     await withEnvAsync({ OPENCLAW_GIT_DIR: tempDir }, async () => {
       setTty(true);

From 98ff2294a93f8f17348ee8c3a7a2f66bc6ef5240 Mon Sep 17 00:00:00 2001
From: Ayaan Zaidi <hi@obviy.us>
Date: Fri, 21 Aug 2026 22:43:11 +0530
Subject: [PATCH 038/124] fix(sessions): preserve sessions when age pruning is
 disabled (#127277)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Non-positive plugin retention now disables age pruning instead of deleting eligible sessions. The disabled path also skips the SQLite stale-row scan and full-store load.

Co-authored-by: Ayaan Zaidi <hi@obviy.us>
Co-authored-by: 曾令彪 0668001395 <zeng.lingbiao@xydigit.com>
---
 .../session-accessor.sqlite-maintenance.ts    |  3 ++
 src/config/sessions/store-maintenance.ts      |  3 ++
 src/plugin-sdk/session-store-runtime.test.ts  | 54 +++++++++----------
 3 files changed, 33 insertions(+), 27 deletions(-)

diff --git a/src/config/sessions/session-accessor.sqlite-maintenance.ts b/src/config/sessions/session-accessor.sqlite-maintenance.ts
index bc571c6b23b7..ba147ded8ad8 100644
--- a/src/config/sessions/session-accessor.sqlite-maintenance.ts
+++ b/src/config/sessions/session-accessor.sqlite-maintenance.ts
@@ -75,6 +75,9 @@ function hasStaleSqliteSessionEntryCandidate(
   maxAgeMs: number,
   isCandidate: (key: string, entry: SessionEntry) => boolean,
 ): boolean {
+  if (maxAgeMs <= 0) {
+    return false;
+  }
   const cutoffMs = Date.now() - maxAgeMs;
   const db = getSessionKysely(database.db);
   const rows = executeSqliteQuerySync(
diff --git a/src/config/sessions/store-maintenance.ts b/src/config/sessions/store-maintenance.ts
index 5b18a542a0fa..c50a22030814 100644
--- a/src/config/sessions/store-maintenance.ts
+++ b/src/config/sessions/store-maintenance.ts
@@ -298,6 +298,9 @@ export function pruneStaleEntries(
   } = {},
 ): number {
   const maxAgeMs = overrideMaxAgeMs ?? resolveMaintenanceConfigFromInput().pruneAfterMs;
+  if (maxAgeMs <= 0) {
+    return 0;
+  }
   const cutoffMs = Date.now() - maxAgeMs;
   let pruned = 0;
   for (const [key, entry] of Object.entries(store)) {
diff --git a/src/plugin-sdk/session-store-runtime.test.ts b/src/plugin-sdk/session-store-runtime.test.ts
index b39bd2fa1651..159e64179938 100644
--- a/src/plugin-sdk/session-store-runtime.test.ts
+++ b/src/plugin-sdk/session-store-runtime.test.ts
@@ -811,45 +811,45 @@ describe("session-store-runtime compatibility surface", () => {
     });
   });
 
-  it("preserves resolved maintenance settings through entry patches", async () => {
-    const staleSessionKey = "agent:main:stale";
-    const activeSessionKey = "agent:main:active";
-    const now = Date.now();
-    await seedSessionEntry(staleSessionKey, {
-      sessionId: "session-stale",
-      updatedAt: now - 8 * DAY_MS,
-    });
-    await seedSessionEntry(activeSessionKey, {
-      sessionId: "session-active",
-      updatedAt: now,
-    });
+  it.each([
+    { pruneAfterMs: 7 * DAY_MS, staleSessionPresent: false },
+    { pruneAfterMs: 0, staleSessionPresent: true },
+    { pruneAfterMs: -DAY_MS, staleSessionPresent: true },
+  ])(
+    "applies age retention $pruneAfterMs through entry patches",
+    async ({ pruneAfterMs, staleSessionPresent }) => {
+      const staleSessionKey = "agent:main:stale";
+      const activeSessionKey = "agent:main:active";
+      const now = Date.now();
+      await seedSessionEntry(staleSessionKey, {
+        sessionId: "session-stale",
+        updatedAt: now - 8 * DAY_MS,
+      });
+      await seedSessionEntry(activeSessionKey, {
+        sessionId: "session-active",
+        updatedAt: now,
+      });
 
-    await expect(
-      patchSessionEntry({
+      await patchSessionEntry({
         sessionKey: activeSessionKey,
         storePath,
         maintenanceConfig: {
           mode: "enforce",
-          pruneAfterMs: 7 * DAY_MS,
+          pruneAfterMs,
           modelRunPruneAfterMs: DAY_MS,
-          maxEntries: 1,
+          maxEntries: 100,
           resetArchiveRetentionMs: 7 * DAY_MS,
           maxDiskBytes: null,
           highWaterBytes: null,
         },
         update: () => ({ model: "gpt-5.5" }),
-      }),
-    ).resolves.toMatchObject({
-      model: "gpt-5.5",
-      sessionId: "session-active",
-    });
+      });
 
-    expect(getSessionEntry({ sessionKey: activeSessionKey, storePath })).toMatchObject({
-      model: "gpt-5.5",
-      sessionId: "session-active",
-    });
-    expect(getSessionEntry({ sessionKey: staleSessionKey, storePath })).toBeUndefined();
-  });
+      expect(getSessionEntry({ sessionKey: staleSessionKey, storePath }) != null).toBe(
+        staleSessionPresent,
+      );
+    },
+  );
 
   it("forwards maintenance suppression through entry patches", async () => {
     const staleSessionKey = "agent:main:stale";

From 0a861b40eef3c859e5f9242c64a4175edad05900 Mon Sep 17 00:00:00 2001
From: ClawSweeper <steipete+clawsweeper@gmail.com>
Date: Fri, 21 Aug 2026 10:19:56 -0700
Subject: [PATCH 039/124] fix(gateway): retain safe side-chat context (#127294)

Co-authored-by: RoboClaw <309084314+roboclaw-bot@users.noreply.github.com>
Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>
---
 src/gateway/session-companion-context.test.ts | 28 +++++++++++++++++++
 src/gateway/session-companion-context.ts      | 18 ++++++++++--
 2 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/src/gateway/session-companion-context.test.ts b/src/gateway/session-companion-context.test.ts
index 52b1b5979f45..e8fc9651821e 100644
--- a/src/gateway/session-companion-context.test.ts
+++ b/src/gateway/session-companion-context.test.ts
@@ -130,6 +130,34 @@ describe("session companion context", () => {
     );
   });
 
+  it("keeps complete recent context when older tool rows exhaust the scan byte budget", async () => {
+    const scope = createScope("companion-context-byte-budget");
+    await upsertSessionEntryCore(scope, { sessionId: scope.sessionId, updatedAt: 1 });
+    const messages = Array.from({ length: 384 }, (_, index) => {
+      const isContextMessage = index % 9 === 0;
+      return {
+        eventId: `message-${index}`,
+        parentId: index === 0 ? null : `message-${index - 1}`,
+        message: isContextMessage
+          ? { role: "user" as const, content: `useful ${index}`, timestamp: index }
+          : { role: "toolResult" as const, content: "x".repeat(4000), timestamp: index },
+      };
+    });
+    await persistSessionTranscriptTurn(scope, { messages, touchSessionEntry: true });
+
+    const result = await defaultSessionCompanionContextReader.read(scope);
+
+    expect(result.kind).toBe("ready");
+    if (result.kind !== "ready") {
+      return;
+    }
+    expect(result.context.messages.length).toBeGreaterThan(0);
+    expect(result.context.messages.at(-1)?.text).toBe("useful 378");
+    expect(result.context.messages.every((message) => message.text.startsWith("useful"))).toBe(
+      true,
+    );
+  });
+
   it.each([
     { expectedKind: "ready", unsupportedCount: 4095 },
     { expectedKind: "unavailable", unsupportedCount: 4096 },
diff --git a/src/gateway/session-companion-context.ts b/src/gateway/session-companion-context.ts
index ee81848baf42..6ef42d05cf05 100644
--- a/src/gateway/session-companion-context.ts
+++ b/src/gateway/session-companion-context.ts
@@ -142,6 +142,7 @@ async function readSessionCompanionContext(params: {
     let rawBytes = 0;
     let scannedMessages = 0;
     let totalMessages = 0;
+    let stoppedAtOlderByteBoundary = false;
     let snapshot:
       | {
           activeLeafEntryId?: string | null;
@@ -163,9 +164,18 @@ async function readSessionCompanionContext(params: {
         ),
         offset,
       });
-      if (params.signal?.aborted || page.events.length !== page.scannedMessages) {
+      if (params.signal?.aborted) {
         return { kind: "unavailable" };
       }
+      if (page.events.length !== page.scannedMessages) {
+        if (contextMessages.length === 0) {
+          return { kind: "unavailable" };
+        }
+        // A partial older page can contain holes around oversized rows. Keep
+        // only the complete newer pages, then verify their snapshot below.
+        stoppedAtOlderByteBoundary = true;
+        break;
+      }
       const pageSnapshot = {
         activeLeafEntryId: page.activeLeafEntryId,
         generation: page.snapshot.generation,
@@ -193,7 +203,11 @@ async function readSessionCompanionContext(params: {
         break;
       }
     }
-    if (contextMessages.length < CONTEXT_MAX_MESSAGES && offset < totalMessages) {
+    if (
+      contextMessages.length < CONTEXT_MAX_MESSAGES &&
+      offset < totalMessages &&
+      !stoppedAtOlderByteBoundary
+    ) {
       return { kind: "unavailable" };
     }
     const fence = readSessionTranscriptBoundedMessageTailPage(scope, {

From f9b5693612ed46b25c2c4b5feaf0c3db628e85cf Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 10:32:36 -0700
Subject: [PATCH 040/124] fix(ui): retire stale plugin lifecycle feedback
 (#127273)

Amp-Thread-ID: https://ampcode.com/threads/T-01a021f4-b547-7788-a916-d4a94cbd3e3b

Co-authored-by: Amp <amp@ampcode.com>
---
 ui/src/pages/plugins/plugins-page.test.ts | 51 +++++++++++++++++++++++
 ui/src/pages/plugins/plugins-page.ts      | 29 +++++++------
 ui/src/pages/plugins/plugins.e2e.test.ts  | 36 ++++++++++++++++
 3 files changed, 104 insertions(+), 12 deletions(-)

diff --git a/ui/src/pages/plugins/plugins-page.test.ts b/ui/src/pages/plugins/plugins-page.test.ts
index 5ddb3bbff3d7..cba49169a8d0 100644
--- a/ui/src/pages/plugins/plugins-page.test.ts
+++ b/ui/src/pages/plugins/plugins-page.test.ts
@@ -760,6 +760,57 @@ describe("PluginsPage", () => {
     expect(calls).toContainEqual(["plugins.list", {}]);
   });
 
+  it("does not let an older uninstall republish its page notice after a newer row action", async () => {
+    const uninstallResult = deferred<unknown>();
+    const enabledPlugin = createPlugin({ enabled: true, state: "enabled" });
+    const removable = createPlugin({
+      id: "community-thing",
+      name: "Community Thing",
+      origin: "global",
+      removable: true,
+      featured: false,
+    });
+    const { client, request } = createClient(async (method) => {
+      if (method === "plugins.uninstall") {
+        return uninstallResult.promise;
+      }
+      if (method === "plugins.setEnabled") {
+        return { ok: true, plugin: enabledPlugin, restartRequired: false };
+      }
+      if (method === "plugins.list") {
+        return createResult(enabledPlugin);
+      }
+      throw new Error(`Unexpected method ${method}`);
+    });
+    const harness = createGateway(client);
+    const { page } = await mountPage(
+      createContext(harness.gateway),
+      createPluginsRouteData(harness.gateway, {
+        plugins: [createPlugin(), removable],
+        diagnostics: [],
+        mutationAllowed: true,
+      }),
+    );
+
+    const uninstall = page.uninstall("community-thing", "plugin:community-thing");
+    await waitForFast(() =>
+      expect(request).toHaveBeenCalledWith("plugins.uninstall", { pluginId: "community-thing" }),
+    );
+    await page.updateEnabled("workboard", true);
+
+    uninstallResult.resolve({
+      ok: true,
+      pluginId: "community-thing",
+      restartRequired: true,
+      removed: ["config entry", "install record", "directory"],
+    });
+    await uninstall;
+    await page.updateComplete;
+
+    expect(page.querySelector(".plugins-page-notice")).toBeNull();
+    expect(page.messages["plugin:workboard"]?.text).toContain("Enabled Workboard");
+  });
+
   it("adds an MCP server through the shared config seam", async () => {
     const { client } = createClient(async (method) => {
       if (method === "plugins.list") {
diff --git a/ui/src/pages/plugins/plugins-page.ts b/ui/src/pages/plugins/plugins-page.ts
index 68b55349eb55..7c6326274b31 100644
--- a/ui/src/pages/plugins/plugins-page.ts
+++ b/ui/src/pages/plugins/plugins-page.ts
@@ -717,6 +717,7 @@ class PluginsPage extends OpenClawLightDomElement {
       refreshError: string | null,
       client: GatewayBrowserClient,
       isCurrent: () => boolean,
+      isLatest: () => boolean,
     ) => Promise<void>,
     onError: (error: unknown) => void = (error) => {
       this.setMessage(rowKey, {
@@ -730,10 +731,12 @@ class PluginsPage extends OpenClawLightDomElement {
     if (!scope || !this.canMutate() || this.busy[rowKey]) {
       return;
     }
+    this.pageNotice = null;
     const mutationToken = ++this.mutationToken;
     this.mutationTokens.set(rowKey, mutationToken);
     const isCurrent = () =>
       this.gateway.isCurrent(scope) && this.mutationTokens.get(rowKey) === mutationToken;
+    const isLatest = () => isCurrent() && this.mutationToken === mutationToken;
     this.setBusy(rowKey, true);
     if (!options.preserveMessageWhilePending) {
       this.setMessage(rowKey, null);
@@ -747,7 +750,7 @@ class PluginsPage extends OpenClawLightDomElement {
       if (!isCurrent()) {
         return;
       }
-      await onSuccess(mutation.value, mutation.refreshError, scope.client, isCurrent);
+      await onSuccess(mutation.value, mutation.refreshError, scope.client, isCurrent, isLatest);
     } catch (error) {
       if (isCurrent()) {
         onError(error);
@@ -840,19 +843,21 @@ class PluginsPage extends OpenClawLightDomElement {
     await this.runPluginMutation(
       rowKey,
       (client) => uninstallPlugin(client, pluginId),
-      async (result, refreshError, client) => {
+      async (result, refreshError, client, _isCurrent, isLatest) => {
         this.setPendingRemoval(rowKey, false);
         // Removal hides its row, so keep the restart reminder on the page.
-        this.pageNotice = {
-          kind: "success",
-          text: [
-            t("pluginsPage.removedRestart", { name: result.pluginId }),
-            ...(result.warnings ?? []).map((warning) => formatUiExternalText(warning)),
-            refreshError ? t("pluginsPage.configRefreshFailed", { error: refreshError }) : null,
-          ]
-            .filter(Boolean)
-            .join("\n"),
-        };
+        if (isLatest()) {
+          this.pageNotice = {
+            kind: "success",
+            text: [
+              t("pluginsPage.removedRestart", { name: result.pluginId }),
+              ...(result.warnings ?? []).map((warning) => formatUiExternalText(warning)),
+              refreshError ? t("pluginsPage.configRefreshFailed", { error: refreshError }) : null,
+            ]
+              .filter(Boolean)
+              .join("\n"),
+          };
+        }
         await this.refreshCatalogAfterMutation(client);
       },
     );
diff --git a/ui/src/pages/plugins/plugins.e2e.test.ts b/ui/src/pages/plugins/plugins.e2e.test.ts
index def3964a4f89..cec933712a9f 100644
--- a/ui/src/pages/plugins/plugins.e2e.test.ts
+++ b/ui/src/pages/plugins/plugins.e2e.test.ts
@@ -676,6 +676,42 @@ describeControlUiE2e("Control UI Plugins mocked Gateway E2E", () => {
         "Removed calendar-plus",
       );
 
+      await gateway.setMethodResponse("plugins.list", uninstalledInventory);
+      await page.getByRole("tab", { name: /^Discover/u }).click();
+      const searchCountBeforeReinstall = (await gateway.getRequests("plugins.search")).length;
+      await page.getByRole("searchbox", { name: "Search plugins" }).fill("calendar");
+      await waitForNextRequest(gateway, "plugins.search", searchCountBeforeReinstall);
+      const reinstallRow = page.locator(
+        '[data-package-name="calendar-plus"][data-plugin-status="not-installed"]',
+      );
+      await reinstallRow.waitFor({ state: "visible" });
+      await gateway.setMethodResponse("plugins.install", installResult);
+      await gateway.setMethodResponse("plugins.list", finalInventory);
+      const installCountBeforeReinstall = (await gateway.getRequests("plugins.install")).length;
+      await reinstallRow
+        .getByRole("button", { name: "Install Calendar Plus", exact: true })
+        .click();
+      const reinstallRequest = await waitForNextRequest(
+        gateway,
+        "plugins.install",
+        installCountBeforeReinstall,
+      );
+      expect(requestParams(reinstallRequest)).toEqual({
+        source: "clawhub",
+        packageName: "calendar-plus",
+      });
+      const reinstalledRow = page.locator(
+        '[data-package-name="calendar-plus"][data-plugin-status="enabled"]',
+      );
+      await reinstalledRow.waitFor({ state: "attached" });
+      await captureScreenshot(page, "11-reinstalled-feedback-desktop.png");
+      expect(await page.locator(".plugins-page-notice").count()).toBe(0);
+      expect(await reinstalledRow.getByRole("status").textContent()).toContain(
+        "Installed Calendar Plus",
+      );
+
+      await page.getByRole("tab", { name: /^Installed/u }).click();
+      await page.getByRole("searchbox", { name: "Search plugins" }).fill("");
       await page.setViewportSize(mobileViewport);
       await expect
         .poll(() =>

From 0c2b224cb07b43eb7811159dd264926c5b9ce039 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 10:37:22 -0700
Subject: [PATCH 041/124] fix(qa): label execution configuration selects
 (#127299)

Amp-Thread-ID: https://ampcode.com/threads/T-01a021f4-b547-7788-a916-d4a94cbd3e3b

Co-authored-by: Amp <amp@ampcode.com>
---
 extensions/qa-lab/web/src/app.browser.test.ts | 32 +++++++++++++++++++
 extensions/qa-lab/web/src/ui-render-shell.ts  | 16 +++++-----
 2 files changed, 40 insertions(+), 8 deletions(-)

diff --git a/extensions/qa-lab/web/src/app.browser.test.ts b/extensions/qa-lab/web/src/app.browser.test.ts
index bb520cbc7084..9467834cd53f 100644
--- a/extensions/qa-lab/web/src/app.browser.test.ts
+++ b/extensions/qa-lab/web/src/app.browser.test.ts
@@ -205,6 +205,38 @@ afterEach(() => {
 });
 
 describe("QA Lab runner browser interactions", () => {
+  it("labels every execution configuration select", async () => {
+    const root = await mountRunner({
+      alternateModel: "mock-openai/gpt-5.6-luna-alt",
+      channel: null,
+      channelDriver: "qa-channel",
+      evidenceMode: "full",
+      fastMode: false,
+      primaryModel: "mock-openai/gpt-5.6-luna",
+      profile: "all",
+      providerMode: "mock-openai",
+      runtimePair: null,
+      runtimePairLane: null,
+      scenarioIds: ["dm-chat-baseline"],
+    });
+
+    root.querySelector<HTMLButtonElement>("[data-sidebar-panel='config']")?.click();
+    const selects = [...root.querySelectorAll<HTMLSelectElement>(".config-field select")];
+
+    expect(selects).toHaveLength(9);
+    expect(selects.map((select) => select.labels?.[0]?.textContent?.trim())).toEqual([
+      "Profile",
+      "Provider lane",
+      "Channel driver",
+      "Execution channel",
+      "Evidence mode",
+      "Runtime pair",
+      "Runtime-pair lane",
+      "Primary model",
+      "Alternate model",
+    ]);
+  });
+
   it("sends group conversation messages from the interactive chat composer", async () => {
     const root = await mountRunner(
       {
diff --git a/extensions/qa-lab/web/src/ui-render-shell.ts b/extensions/qa-lab/web/src/ui-render-shell.ts
index e760372c9960..1ff93ac76e85 100644
--- a/extensions/qa-lab/web/src/ui-render-shell.ts
+++ b/extensions/qa-lab/web/src/ui-render-shell.ts
@@ -72,7 +72,7 @@ function renderModelSelect(params: {
   }
   return `
     <div class="config-field">
-      <span class="config-label">${esc(params.label)}</span>
+      <label class="config-label" for="${esc(params.id)}">${esc(params.label)}</label>
       <select id="${esc(params.id)}"${params.disabled ? " disabled" : ""}>
         ${options
           .map(
@@ -117,7 +117,7 @@ export function renderSidebar(state: UiState): string {
           ? `<div class="sidebar-section sidebar-panel-body">
               <div class="sidebar-section-title"><h3>Configuration</h3></div>
               <div class="config-field">
-                <span class="config-label">Profile</span>
+                <label class="config-label" for="run-profile">Profile</label>
                 <select id="run-profile"${isRunning ? " disabled" : ""}>
                   ${profiles
                     .map(
@@ -128,14 +128,14 @@ export function renderSidebar(state: UiState): string {
                 </select>
               </div>
               <div class="config-field">
-                <span class="config-label">Provider lane</span>
+                <label class="config-label" for="provider-mode">Provider lane</label>
                 <select id="provider-mode"${isRunning ? " disabled" : ""}>
                   <option value="mock-openai"${selection?.providerMode === "mock-openai" ? " selected" : ""}>Synthetic (mock)</option>
                   <option value="live-frontier"${selection?.providerMode === "live-frontier" ? " selected" : ""}>Real frontier providers</option>
                 </select>
               </div>
               <div class="config-field">
-                <span class="config-label">Channel driver</span>
+                <label class="config-label" for="channel-driver">Channel driver</label>
                 <select id="channel-driver"${isRunning ? " disabled" : ""}>
                   <option value="qa-channel"${selection?.channelDriver === "qa-channel" ? " selected" : ""}>Synthetic QA channel</option>
                   <option value="crabline"${selection?.channelDriver === "crabline" ? " selected" : ""}>Crabline channel driver</option>
@@ -143,7 +143,7 @@ export function renderSidebar(state: UiState): string {
                 </select>
               </div>
               <div class="config-field">
-                <span class="config-label">Execution channel</span>
+                <label class="config-label" for="execution-channel">Execution channel</label>
                 <select id="execution-channel"${isRunning ? " disabled" : ""}>
                   <option value=""${selection?.channel ? "" : " selected"}>Catalog/default</option>
                   ${channels
@@ -155,21 +155,21 @@ export function renderSidebar(state: UiState): string {
                 </select>
               </div>
               <div class="config-field">
-                <span class="config-label">Evidence mode</span>
+                <label class="config-label" for="evidence-mode">Evidence mode</label>
                 <select id="evidence-mode"${isRunning ? " disabled" : ""}>
                   <option value="full"${selection?.evidenceMode === "full" ? " selected" : ""}>Full</option>
                   <option value="slim"${selection?.evidenceMode === "slim" ? " selected" : ""}>Slim</option>
                 </select>
               </div>
               <div class="config-field">
-                <span class="config-label">Runtime pair</span>
+                <label class="config-label" for="runtime-pair">Runtime pair</label>
                 <select id="runtime-pair"${isRunning ? " disabled" : ""}>
                   <option value=""${selection?.runtimePair ? "" : " selected"}>Single runtime</option>
                   <option value="openclaw,codex"${selection?.runtimePair ? " selected" : ""}>OpenClaw × Codex</option>
                 </select>
               </div>
               <div class="config-field">
-                <span class="config-label">Runtime-pair lane</span>
+                <label class="config-label" for="runtime-pair-lane">Runtime-pair lane</label>
                 <select id="runtime-pair-lane"${isRunning ? " disabled" : ""}>
                   <option value=""${selection?.runtimePairLane ? "" : " selected"}>Profile/default</option>
                   ${(["core", "extended", "soak"] as const)

From 10a3df4fb6997b90fcb5ff0c7c890ae22c57abb6 Mon Sep 17 00:00:00 2001
From: Ayaan Zaidi <hi@obviy.us>
Date: Fri, 21 Aug 2026 23:09:17 +0530
Subject: [PATCH 042/124] feat(mantis): let proof agents extend desktop control
 (#127271)

* feat(mantis): let proof agents extend desktop control

* fix(mantis): constrain desktop extensions

* docs(mantis): document desktop action authority

* fix(mantis): bind actions to recorded window
---
 .../prompts/mantis-telegram-desktop-proof.md  |  13 +-
 docs/concepts/mantis.md                       |  11 +-
 .../e2e/telegram-desktop-recorder-contract.ts |  32 ++++-
 scripts/e2e/telegram-desktop-recorder.ts      | 114 ++++++++++++++++--
 scripts/e2e/telegram-mantis-lane.ts           |  53 ++++++++
 .../scripts/telegram-desktop-recorder.test.ts |  95 +++++++++++++--
 test/scripts/telegram-mantis-lane.test.ts     |  59 ++++++++-
 7 files changed, 348 insertions(+), 29 deletions(-)

diff --git a/.github/codex/prompts/mantis-telegram-desktop-proof.md b/.github/codex/prompts/mantis-telegram-desktop-proof.md
index 9f78f5c56071..f343a37af154 100644
--- a/.github/codex/prompts/mantis-telegram-desktop-proof.md
+++ b/.github/codex/prompts/mantis-telegram-desktop-proof.md
@@ -63,15 +63,22 @@ Use `$OPENCLAW_TELEGRAM_MANTIS_LANE_CMD` with `--lane baseline|candidate`:
 - `requests` (redacted provider requests; zero is a valid recorded fact)
 - `press --message-id ID --button INDEX`
 - `delete --message-id ID` (only user messages sent in this session)
+- `desktop --actions-file <public-json> [--timeout-seconds N]` (run an
+  agent-authored click/key/type/sleep action sequence in the recorded desktop)
 - `view --message-id ID` (scroll Desktop to the exact Telegram server message)
 - `screenshot` (returns a public inspection PNG)
 - `finish [--focus-message-id ID]` (focus the named message or the latest sent message, stop, capture, publish facts)
 - `block --reason TEXT [--missing-primitive NAME]` (clean stop-report)
 - `abort` (cleanup after scenario failure)
 
-`start` returns the exact command/budget list. No generic exec/eval or raw
-Telegram API exists. If the comparison cannot prove the PR's visible behavior,
-use `block` and say why.
+`start` returns the exact command/budget list. When the listed primitives cannot
+exercise the behavior, extend the harness: write a focused JSON action sequence
+under `MANTIS_OUTPUT_DIR` and run it with `desktop`. Actions use Telegram-window
+coordinates: `{"command":"click","x":N,"y":N,"button":1}`,
+`{"command":"key","keys":["ctrl+a"]}`, `{"command":"type","text":"..."}`,
+or `{"command":"sleep","milliseconds":N}`. Inspect a screenshot, adjust the
+sequence, and continue the proof. Use `block` only when the ephemeral desktop
+itself cannot exercise the behavior.
 Raw response events must form a complete provider response; deltas alone do not
 produce a final answer. Copy the terminal item and completed-response structure
 from `responseEvents` in `scripts/e2e/mock-openai-server.mjs`, and use
diff --git a/docs/concepts/mantis.md b/docs/concepts/mantis.md
index d49446df4ab6..32440b4df479 100644
--- a/docs/concepts/mantis.md
+++ b/docs/concepts/mantis.md
@@ -202,10 +202,13 @@ in.
 ### Telegram Desktop recorder
 
 The Telegram Desktop recorder is a standalone operator utility, invoked
-directly through `pnpm qa:telegram-desktop-recorder`. It records native
-Telegram Desktop and nothing else: it never drives OpenClaw or sends Telegram
-messages. Whoever runs it owns the turn — start the SUT, send through a real
-Telegram user, then tell the recorder which message to show — and supplies
+directly through `pnpm qa:telegram-desktop-recorder`. It never drives OpenClaw.
+Its normal recording commands do not send Telegram messages. The optional
+`actions` command drives only the measured Telegram window through bounded
+`click`, `key`, `type`, and `sleep` actions; those actions can send as the
+signed-in Telegram user. Whoever runs it owns the turn and those side effects —
+start the SUT, send through a real Telegram user, then tell the recorder which
+message to show — and supplies
 `--user-driver`, the command the recorder shells out to for the TDLib calls it
 cannot make itself (`confirm-qr`, `terminate-session`). Any driver exposing
 those two verbs works, including this repo's
diff --git a/scripts/e2e/telegram-desktop-recorder-contract.ts b/scripts/e2e/telegram-desktop-recorder-contract.ts
index 2861cdfba7a7..47c65ff0413c 100644
--- a/scripts/e2e/telegram-desktop-recorder-contract.ts
+++ b/scripts/e2e/telegram-desktop-recorder-contract.ts
@@ -27,6 +27,7 @@ const recorderSessionBaseSchema = z.object({
   /** Telegram Desktop window as placed on the recorded desktop; the crop uses it. */
   window: z.object({
     height: z.number().int().positive(),
+    id: z.string().regex(/^0x[0-9a-f]+$/iu),
     width: z.number().int().positive(),
     x: z.number().int().nonnegative(),
     y: z.number().int().nonnegative(),
@@ -70,6 +71,13 @@ export type ViewOptions = {
   sessionPath: string;
 };
 
+export type ActionsOptions = {
+  actionsFile: string;
+  command: "actions";
+  sessionPath: string;
+  timeoutSeconds: number;
+};
+
 export type ScreenshotOptions = {
   command: "screenshot";
   output?: string;
@@ -100,6 +108,7 @@ export type ArtifactsOptions = {
 
 type RecorderOptions =
   | ArtifactsOptions
+  | ActionsOptions
   | RecoverOptions
   | ScreenshotOptions
   | StartOptions
@@ -113,6 +122,7 @@ export function recorderUsageText(): string {
     "  pnpm qa:telegram-desktop-recorder artifacts --session <recorder.json>",
     '  pnpm qa:telegram-desktop-recorder start --output-dir <dir> --chat <-100groupId> --user-driver "<space-separated cmd prefix>" [options]',
     "  pnpm qa:telegram-desktop-recorder view --session <recorder.json> --message-id <id>",
+    "  pnpm qa:telegram-desktop-recorder actions --session <recorder.json> --actions-file <json> [--timeout-seconds <seconds>]",
     "  pnpm qa:telegram-desktop-recorder screenshot --session <recorder.json> [--output <png>]",
     "  pnpm qa:telegram-desktop-recorder recover --session <recorder.json>",
     "  pnpm qa:telegram-desktop-recorder stop --session <recorder.json> [--crop telegram-window] [--keep-box]",
@@ -163,7 +173,7 @@ export function parseRecorderArgs(argv: string[]): RecorderOptions {
     throw new Error(recorderUsageText());
   }
   const parsedCommand = z
-    .enum(["artifacts", "recover", "screenshot", "start", "status", "stop", "view"])
+    .enum(["actions", "artifacts", "recover", "screenshot", "start", "status", "stop", "view"])
     .safeParse(rawCommand);
   if (!parsedCommand.success) {
     throw new Error(`Unknown command: ${rawCommand}\n\n${recorderUsageText()}`);
@@ -205,11 +215,13 @@ export function parseRecorderArgs(argv: string[]): RecorderOptions {
         ])
       : command === "view"
         ? new Set(["--message-id", "--session"])
-        : command === "screenshot"
-          ? new Set(["--output", "--session"])
-          : command === "stop"
-            ? new Set(["--crop", "--session"])
-            : new Set(["--session"]);
+        : command === "actions"
+          ? new Set(["--actions-file", "--session", "--timeout-seconds"])
+          : command === "screenshot"
+            ? new Set(["--output", "--session"])
+            : command === "stop"
+              ? new Set(["--crop", "--session"])
+              : new Set(["--session"]);
   for (const flag of values.keys()) {
     if (!allowed.has(flag)) {
       throw new Error(`${flag} is not available for ${command}.`);
@@ -266,6 +278,14 @@ export function parseRecorderArgs(argv: string[]): RecorderOptions {
     positiveInteger(messageId, "--message-id");
     return { command, messageId, sessionPath };
   }
+  if (command === "actions") {
+    return {
+      actionsFile: requiredString(values, "--actions-file"),
+      command,
+      sessionPath,
+      timeoutSeconds: positiveInteger(values.get("--timeout-seconds") ?? "60", "--timeout-seconds"),
+    };
+  }
   if (command === "screenshot") {
     return { command, output: values.get("--output"), sessionPath };
   }
diff --git a/scripts/e2e/telegram-desktop-recorder.ts b/scripts/e2e/telegram-desktop-recorder.ts
index 2c7c85a6a6bb..1d1e3a223576 100644
--- a/scripts/e2e/telegram-desktop-recorder.ts
+++ b/scripts/e2e/telegram-desktop-recorder.ts
@@ -26,6 +26,7 @@ import {
 import {
   parseRecorderArgs,
   readRecorderSession,
+  type ActionsOptions,
   type ArtifactsOptions,
   type RecoverOptions,
   recorderUsageText,
@@ -174,14 +175,13 @@ export DISPLAY=:99
 win="$(wmctrl -lx | awk 'tolower($0) ~ /telegramdesktop/ {print $1; exit}')"
 test -n "$win"
 eval "$(xdotool getwindowgeometry --shell "$win")"
-printf '%s %s %s %s\n' "$X" "$Y" "$WIDTH" "$HEIGHT"`;
+printf '%s %s %s %s %s\n' "$win" "$X" "$Y" "$WIDTH" "$HEIGHT"`;
 }
 
-function renderHideTelegramWindow(): string {
+function renderHideTelegramWindow(windowId: string): string {
   return `set -euo pipefail
 export DISPLAY=:99
-win="$(wmctrl -lx | awk 'tolower($0) ~ /telegramdesktop/ {print $1; exit}')"
-test -n "$win"
+win=${shellQuote(windowId)}
 xdotool windowminimize "$win"
 sleep 0.2`;
 }
@@ -236,19 +236,26 @@ exit 1`;
 
 export function parseWindowGeometry(raw: string): {
   height: number;
+  id: string;
   width: number;
   x: number;
   y: number;
 } {
-  const parts = raw.trim().split(/\s+/u).map(Number);
-  if (parts.length !== 4 || parts.some((value) => !Number.isFinite(value) || value < 0)) {
+  const [id, ...rawGeometry] = raw.trim().split(/\s+/u);
+  const parts = rawGeometry.map(Number);
+  if (
+    !id ||
+    !/^0x[0-9a-f]+$/iu.test(id) ||
+    parts.length !== 4 ||
+    parts.some((value) => !Number.isFinite(value) || value < 0)
+  ) {
     throw new Error(`Telegram Desktop window geometry was not readable: ${raw.trim()}`);
   }
   const [x, y, width, height] = parts as [number, number, number, number];
   if (width < 200 || height < 200) {
     throw new Error(`Telegram Desktop window is too small to crop: ${width}x${height}`);
   }
-  return { height, width, x, y };
+  return { height, id, width, x, y };
 }
 
 function driverCommand(userDriver: string[], args: string[]) {
@@ -611,7 +618,7 @@ async function startRecorderAttempt(
     // The lane clears prior history before recorder start. Keep the empty chat hidden until
     // the first session-owned send is ready, so setup frames reveal neither account UI nor chat.
     await operations.sshRun({
-      command: renderHideTelegramWindow(),
+      command: renderHideTelegramWindow(windowGeometry.id),
       cwd,
       inspect,
       run: operations.runCommand,
@@ -815,6 +822,93 @@ export async function viewRecorder(
   });
 }
 
+const desktopActionsSchema = z
+  .array(
+    z.discriminatedUnion("command", [
+      z.object({
+        button: z.number().int().min(1).max(5).default(1),
+        command: z.literal("click"),
+        x: z.number().int().nonnegative(),
+        y: z.number().int().nonnegative(),
+      }),
+      z.object({
+        command: z.literal("key"),
+        keys: z
+          .array(z.string().regex(/^[A-Za-z0-9_+:-]+$/u))
+          .min(1)
+          .max(20),
+      }),
+      z.object({ command: z.literal("sleep"), milliseconds: z.number().int().min(1).max(30_000) }),
+      z.object({
+        command: z.literal("type"),
+        delayMs: z.number().int().min(0).max(1_000).default(5),
+        text: z.string().min(1).max(10_000),
+      }),
+    ]),
+  )
+  .min(1)
+  .max(100);
+
+export async function runRecorderActions(
+  cwd: string,
+  opts: ActionsOptions,
+  operations: RecorderOperations = defaultOperations,
+): Promise<{ results: Array<{ command: string; stderr: string; stdout: string }> }> {
+  const sessionPath = resolveRecorderPath(cwd, opts.sessionPath, "--session");
+  const actionsPath = resolveRecorderPath(cwd, opts.actionsFile, "--actions-file");
+  const actionsStat = fs.lstatSync(actionsPath);
+  if (!actionsStat.isFile() || actionsStat.isSymbolicLink() || actionsStat.size > 64 * 1024) {
+    throw new Error("--actions-file must be a regular file no larger than 64 KiB.");
+  }
+  const actions = desktopActionsSchema.parse(JSON.parse(fs.readFileSync(actionsPath, "utf8")));
+  const session = readRecorderSession(sessionPath);
+  for (const action of actions) {
+    if (
+      action.command === "click" &&
+      (action.x >= session.window.width || action.y >= session.window.height)
+    ) {
+      throw new Error("click coordinates must stay inside the Telegram window.");
+    }
+  }
+  const crabboxBin = process.env.OPENCLAW_TELEGRAM_USER_CRABBOX_BIN?.trim() || "crabbox";
+  const inspect = await sessionInspect({ crabboxBin, cwd, operations, session });
+  const results: Array<{ command: string; stderr: string; stdout: string }> = [];
+  for (const action of actions) {
+    if (action.command === "sleep") {
+      await sleep(action.milliseconds);
+      results.push({ command: "sleep", stderr: "", stdout: "" });
+      continue;
+    }
+    const telegramWindow = `win=${shellQuote(session.window.id)}
+if ! wmctrl -lx | awk -v win="$win" 'tolower($1) == tolower(win) && tolower($0) ~ /telegramdesktop/ {found=1} END {exit !found}'; then
+  echo "Recorded Telegram window $win no longer exists." >&2
+  exit 1
+fi
+eval "$(xdotool getwindowgeometry --shell "$win")"
+if [ "$X" -ne ${session.window.x} ] || [ "$Y" -ne ${session.window.y} ] || [ "$WIDTH" -ne ${session.window.width} ] || [ "$HEIGHT" -ne ${session.window.height} ]; then
+  echo "Recorded Telegram window $win moved or resized." >&2
+  exit 1
+fi
+`;
+    const actionCommand =
+      action.command === "click"
+        ? `xdotool windowactivate --sync "$win" mousemove --window "$win" ${action.x} ${action.y} click ${action.button}`
+        : action.command === "key"
+          ? `xdotool key --window "$win" ${action.keys.map(shellQuote).join(" ")}`
+          : `xdotool type --window "$win" --delay ${action.delayMs} -- ${shellQuote(action.text)}`;
+    const result = await operations.sshRun({
+      command: `export DISPLAY=:99\n${telegramWindow}${actionCommand}`,
+      cwd,
+      inspect,
+      run: operations.runCommand,
+      stdio: "pipe",
+      timeoutMs: opts.timeoutSeconds * 1000,
+    });
+    results.push({ command: action.command, ...result });
+  }
+  return { results };
+}
+
 async function captureScreenshot(params: {
   crop: ReturnType<typeof proofViewport>;
   cwd: string;
@@ -1067,6 +1161,10 @@ async function main(): Promise<void> {
     console.log(`Telegram Desktop opened message ${opts.messageId}.`);
     return;
   }
+  if (opts.command === "actions") {
+    console.log(JSON.stringify(await runRecorderActions(cwd, opts), null, 2));
+    return;
+  }
   if (opts.command === "screenshot") {
     console.log(await screenshotRecorder(cwd, opts));
     return;
diff --git a/scripts/e2e/telegram-mantis-lane.ts b/scripts/e2e/telegram-mantis-lane.ts
index 2b4460cd2a47..b1ee44e27066 100644
--- a/scripts/e2e/telegram-mantis-lane.ts
+++ b/scripts/e2e/telegram-mantis-lane.ts
@@ -112,6 +112,7 @@ const commandOptions: Record<string, readonly string[]> = {
   abort: ["--lane"],
   block: ["--lane", "--missing-primitive", "--reason"],
   delete: ["--lane", "--message-id"],
+  desktop: ["--lane", "--actions-file", "--timeout-seconds"],
   finish: ["--lane", "--focus-message-id"],
   mock: ["--lane", "--response-file", "--response-events-file", "--chunk-delay-ms"],
   observe: ["--lane", "--seconds", "--since"],
@@ -1033,6 +1034,56 @@ async function observerAction(
   return response;
 }
 
+async function runDesktopActions(
+  state: ActiveSession,
+  values: Map<string, string>,
+  roots: Roots,
+): Promise<Record<string, unknown>> {
+  const actions = readPublicFile(
+    roots.outputRoot,
+    required(values, "--actions-file"),
+    "--actions-file",
+    64 * 1024,
+  );
+  if (!actions.text.trim()) {
+    throw new Error("--actions-file must not be empty.");
+  }
+  const timeoutSeconds = values.has("--timeout-seconds")
+    ? numberOption(values, "--timeout-seconds", 300, 1)
+    : 60;
+  const privateActions = path.join(
+    state.privateDir,
+    `desktop-actions-${state.invocations.length + 1}.json`,
+  );
+  fs.mkdirSync(state.privateDir, { recursive: true });
+  fs.writeFileSync(privateActions, actions.text, { mode: 0o640 });
+  const actionsSha256 = createHash("sha256").update(actions.text).digest("hex");
+  appendInvocation(state, "desktop", {
+    actionsFile: actions.relative,
+    actionsSha256,
+    timeoutSeconds,
+  });
+  saveActive(roots.sessionRoot, state);
+  const result = z
+    .object({
+      results: z.array(z.object({ command: z.string(), stderr: z.string(), stdout: z.string() })),
+    })
+    .parse(
+      JSON.parse(
+        await runCommandOutput(requiredEnv("OPENCLAW_TELEGRAM_DESKTOP_RECORDER_CMD"), [
+          "actions",
+          "--session",
+          recorderRelativePath(state.recorderSession),
+          "--actions-file",
+          recorderRelativePath(privateActions),
+          "--timeout-seconds",
+          String(timeoutSeconds),
+        ]),
+      ),
+    );
+  return { ...result, actionsSha256 };
+}
+
 async function focusMessage(state: ActiveSession, messageId: string): Promise<void> {
   if (!/^\d+$/u.test(messageId) || BigInt(messageId) < 1n) {
     throw new Error("--message-id must be a positive Telegram server message id.");
@@ -1445,6 +1496,8 @@ async function main(): Promise<void> {
     const credential = credentialSchema.parse(readJson(roots.credentialFile));
     if (cli.command === "mock") {
       outputJson(updateMockResponse(state, cli.values, roots.outputRoot));
+    } else if (cli.command === "desktop") {
+      outputJson(await runDesktopActions(state, cli.values, roots));
     } else if (cli.command === "send") {
       const sent = await sendVisibleMessage(state, cli.values, roots, credential.sutToken);
       outputJson({ ...sent.response, revealedMessageId: sent.revealedMessageId });
diff --git a/test/scripts/telegram-desktop-recorder.test.ts b/test/scripts/telegram-desktop-recorder.test.ts
index f09b977e7ff0..0798dd068495 100644
--- a/test/scripts/telegram-desktop-recorder.test.ts
+++ b/test/scripts/telegram-desktop-recorder.test.ts
@@ -14,6 +14,7 @@ import {
   readRecorderSession,
   recoverRecorderStartup,
   recorderArtifacts,
+  runRecorderActions,
   screenshotRecorder,
   type RecorderOperations,
   type RecorderSession,
@@ -59,7 +60,7 @@ function testSession(): RecorderSession {
     },
     schemaVersion: 1,
     startedAt: "2026-08-15T12:00:00.000Z",
-    window: { height: 1000, width: 650, x: 635, y: 40 },
+    window: { height: 1000, id: "0x04600007", width: 650, x: 635, y: 40 },
     userDriver: ["python3", "driver.py", "--account", "qa shared"],
   };
 }
@@ -133,6 +134,85 @@ describe("Telegram Desktop recorder CLI", () => {
       command: "artifacts",
       sessionPath: "recorder.json",
     });
+    expect(
+      parseRecorderArgs([
+        "actions",
+        "--session",
+        "recorder.json",
+        "--actions-file",
+        "click.json",
+        "--timeout-seconds",
+        "90",
+      ]),
+    ).toEqual({
+      actionsFile: "click.json",
+      command: "actions",
+      sessionPath: "recorder.json",
+      timeoutSeconds: 90,
+    });
+  });
+
+  it("targets the recorded Telegram window instead of the first matching window", async () => {
+    const root = makeTempDir();
+    const sessionPath = path.join(root, "recorder.json");
+    const actionsPath = path.join(root, "click.json");
+    writeRecorderSession(sessionPath, testSession());
+    fs.writeFileSync(
+      actionsPath,
+      JSON.stringify([
+        { command: "click", x: 120, y: 240 },
+        { command: "sleep", milliseconds: 5 },
+      ]),
+    );
+    const sshRun = vi.fn<RecorderOperations["sshRun"]>(async () => ({
+      stderr: "",
+      stdout: "clicked\n",
+    }));
+    const operations = {
+      createCroppedMotionPreview: vi.fn(async () => ({ crop: "", fps: 24, outputWidth: 650 })),
+      createMotionPreview: vi.fn(async () => ({})),
+      inspectCrabbox: vi.fn(async () => ({
+        sshHost: "host",
+        sshKey: "/tmp/key",
+        sshPort: "22",
+        sshUser: "user",
+      })),
+      runCommand: vi.fn(async () => ({ stderr: "", stdout: "" })),
+      scpFromRemote: vi.fn(async () => undefined),
+      sshRun,
+    } satisfies RecorderOperations;
+
+    await expect(
+      runRecorderActions(
+        root,
+        {
+          actionsFile: "click.json",
+          command: "actions",
+          sessionPath: "recorder.json",
+          timeoutSeconds: 90,
+        },
+        operations,
+      ),
+    ).resolves.toEqual({
+      results: [
+        { command: "click", stderr: "", stdout: "clicked\n" },
+        { command: "sleep", stderr: "", stdout: "" },
+      ],
+    });
+    expect(sshRun).toHaveBeenCalledWith(
+      expect.objectContaining({
+        command: expect.stringContaining(
+          'xdotool windowactivate --sync "$win" mousemove --window "$win" 120 240 click 1',
+        ),
+        stdio: "pipe",
+        timeoutMs: 90_000,
+      }),
+    );
+    const actionCommand = sshRun.mock.calls[0]?.[0].command;
+    expect(actionCommand).toContain("win='0x04600007'");
+    expect(actionCommand).toContain("tolower($1) == tolower(win)");
+    expect(actionCommand).toContain('[ "$WIDTH" -ne 650 ]');
+    expect(actionCommand).not.toContain("{print $1; exit}");
   });
 
   it("requires start inputs and a -100 private-group chat id", () => {
@@ -465,7 +545,7 @@ describe("Telegram Desktop recorder remote contract", () => {
           throw new Error("first desktop stayed on QR");
         }
         if (command.includes("getwindowgeometry")) {
-          return { stderr: "", stdout: "635 40 650 1000" };
+          return { stderr: "", stdout: "0x04600007 635 40 650 1000" };
         }
         return { stderr: "", stdout: "" };
       }),
@@ -504,7 +584,7 @@ describe("Telegram Desktop recorder remote contract", () => {
         return { stderr: "", stdout: "tg://login?token=open-target-chat" };
       }
       if (command.includes("getwindowgeometry")) {
-        return { stderr: "", stdout: "635 40 650 1000" };
+        return { stderr: "", stdout: "0x04600007 635 40 650 1000" };
       }
       return { stderr: "", stdout: "" };
     });
@@ -785,14 +865,15 @@ describe("Telegram Desktop recorder window geometry", () => {
   });
 
   it("parses the measured window and rejects unusable geometry", () => {
-    expect(parseWindowGeometry(" 636 45 648 995 \n")).toEqual({
+    expect(parseWindowGeometry(" 0x04600007 636 45 648 995 \n")).toEqual({
       height: 995,
+      id: "0x04600007",
       width: 648,
       x: 636,
       y: 45,
     });
-    expect(() => parseWindowGeometry("636 45 648")).toThrow("was not readable");
-    expect(() => parseWindowGeometry("636 45 10 10")).toThrow("too small to crop");
+    expect(() => parseWindowGeometry("0x04600007 636 45 648")).toThrow("was not readable");
+    expect(() => parseWindowGeometry("0x04600007 636 45 10 10")).toThrow("too small to crop");
   });
 
   it("crops the recorded window instead of a fixed rectangle", async () => {
@@ -800,7 +881,7 @@ describe("Telegram Desktop recorder window geometry", () => {
     const sessionPath = path.join(root, "recorder.json");
     writeRecorderSession(sessionPath, {
       ...testSession(),
-      window: { height: 995, width: 648, x: 636, y: 45 },
+      window: { height: 995, id: "0x04600007", width: 648, x: 636, y: 45 },
     });
     const cropped = vi.fn(async () => ({ crop: "", fps: 24, outputWidth: 648 }));
     const sshRun = vi.fn<RecorderOperations["sshRun"]>(async () => ({ stderr: "", stdout: "" }));
diff --git a/test/scripts/telegram-mantis-lane.test.ts b/test/scripts/telegram-mantis-lane.test.ts
index 7563e9e14574..7c4d8b869122 100644
--- a/test/scripts/telegram-mantis-lane.test.ts
+++ b/test/scripts/telegram-mantis-lane.test.ts
@@ -52,7 +52,7 @@ async function setupHarness(
   fs.writeFileSync(trimmedVideo, Buffer.alloc(10_001));
   fs.writeFileSync(
     recorderCommand,
-    `#!/bin/sh\nprintf '%s\\n' "$*" >> ${JSON.stringify(recorderLog)}\ncp ${JSON.stringify(path.join(root, "mock-response.json"))} ${JSON.stringify(recorderControlLog)}\n${options.failRecorder ? "exit 1\n" : ""}if [ "$1" = artifacts ]; then\n  printf '%s\\n' ${JSON.stringify(JSON.stringify({ artifacts: { previewGifCropped: previewGif, screenshot, trimmedVideoCropped: trimmedVideo } }))}\nfi\n`,
+    `#!/bin/sh\nprintf '%s\\n' "$*" >> ${JSON.stringify(recorderLog)}\ncp ${JSON.stringify(path.join(root, "mock-response.json"))} ${JSON.stringify(recorderControlLog)}\n${options.failRecorder ? "exit 1\n" : ""}if [ "$1" = artifacts ]; then\n  printf '%s\\n' ${JSON.stringify(JSON.stringify({ artifacts: { previewGifCropped: previewGif, screenshot, trimmedVideoCropped: trimmedVideo } }))}\nelif [ "$1" = actions ]; then\n  printf '%s\\n' ${JSON.stringify(JSON.stringify({ results: [{ command: "click", stderr: "", stdout: "clicked\n" }] }))}\nfi\n`,
     { mode: 0o755 },
   );
   fs.writeFileSync(userDriverCommand, "#!/bin/sh\nexit 0\n", { mode: 0o755 });
@@ -340,6 +340,63 @@ describe("Telegram Mantis free-form lane", () => {
     }
   });
 
+  it("runs scenario-authored actions inside the ephemeral desktop", async () => {
+    const harness = await setupHarness();
+    const actions = path.join(harness.outputRoot, "click-picker.json");
+    fs.writeFileSync(actions, JSON.stringify([{ command: "click", x: 120, y: 240 }]));
+    try {
+      const result = await runLane(harness.env, [
+        "desktop",
+        "--lane",
+        "candidate",
+        "--actions-file",
+        actions,
+        "--timeout-seconds",
+        "90",
+      ]);
+      expect(JSON.parse(result.stdout)).toMatchObject({
+        actionsSha256: expect.stringMatching(/^[0-9a-f]{64}$/u),
+        results: [{ command: "click", stdout: "clicked\n" }],
+      });
+      expect(fs.readFileSync(harness.recorderLog, "utf8")).toContain(
+        "actions --session attempt/recorder.json --actions-file attempt/desktop-actions-2.json --timeout-seconds 90",
+      );
+      const state = JSON.parse(
+        fs.readFileSync(path.join(harness.sessionRoot, "candidate.active.json"), "utf8"),
+      );
+      expect(state.invocations.at(-1)).toMatchObject({
+        args: { actionsFile: "click-picker.json", timeoutSeconds: 90 },
+        command: "desktop",
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it("records desktop actions before a timeout or failure", async () => {
+    const harness = await setupHarness({ failRecorder: true });
+    const actions = path.join(harness.outputRoot, "failed-actions.json");
+    fs.writeFileSync(actions, JSON.stringify([{ command: "click", x: 120, y: 240 }]));
+    try {
+      await expect(
+        runLane(harness.env, ["desktop", "--lane", "candidate", "--actions-file", actions]),
+      ).rejects.toThrow();
+      const state = JSON.parse(
+        fs.readFileSync(path.join(harness.sessionRoot, "candidate.active.json"), "utf8"),
+      );
+      expect(state.invocations.at(-1)).toMatchObject({
+        args: {
+          actionsFile: "failed-actions.json",
+          actionsSha256: expect.stringMatching(/^[0-9a-f]{64}$/u),
+          timeoutSeconds: 60,
+        },
+        command: "desktop",
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
   it("retains the sent message when revealing it fails", async () => {
     const harness = await setupHarness({ failRecorder: true });
     try {

From b9dda9d740fd6cfd4032ae2034b8022da954e4a0 Mon Sep 17 00:00:00 2001
From: Dallin Romney <dallinromney@gmail.com>
Date: Fri, 21 Aug 2026 10:45:04 -0700
Subject: [PATCH 043/124] fix(diffs): load Playwright renderer on demand
 (#127040)

* fix(diffs): load Playwright renderer on demand

* style(diffs): format lazy renderer construction

* fix(diffs): keep viewer mode free of Playwright

* fix(diffs): preserve viewer fallback on renderer load failure

* test(diffs): satisfy result narrowing lint

* refactor(diffs): centralize lazy renderer runtime
---
 .../diffs/plugin-startup-laziness.test.ts     | 11 ++++++++
 ...rowser.test.ts => browser.runtime.test.ts} |  4 +--
 .../src/{browser.ts => browser.runtime.ts}    |  0
 .../diffs/src/tool-render-output.test.ts      |  2 +-
 extensions/diffs/src/tool.test.ts             | 26 ++++++++++++++++++-
 extensions/diffs/src/tool.ts                  | 15 ++++++++---
 6 files changed, 50 insertions(+), 8 deletions(-)
 create mode 100644 extensions/diffs/plugin-startup-laziness.test.ts
 rename extensions/diffs/src/{browser.test.ts => browser.runtime.test.ts} (99%)
 rename extensions/diffs/src/{browser.ts => browser.runtime.ts} (100%)

diff --git a/extensions/diffs/plugin-startup-laziness.test.ts b/extensions/diffs/plugin-startup-laziness.test.ts
new file mode 100644
index 000000000000..acf3bc0075a1
--- /dev/null
+++ b/extensions/diffs/plugin-startup-laziness.test.ts
@@ -0,0 +1,11 @@
+import { expect, it, vi } from "vitest";
+
+vi.mock("./src/browser.runtime.js", () => {
+  throw new Error("plugin startup must not load the Playwright renderer");
+});
+
+it("imports the plugin entry without loading the Playwright renderer", async () => {
+  const { default: plugin } = await import("./index.js");
+
+  expect(plugin.id).toBe("diffs");
+});
diff --git a/extensions/diffs/src/browser.test.ts b/extensions/diffs/src/browser.runtime.test.ts
similarity index 99%
rename from extensions/diffs/src/browser.test.ts
rename to extensions/diffs/src/browser.runtime.test.ts
index ec9cb0b78b57..66c5b416ae2a 100644
--- a/extensions/diffs/src/browser.test.ts
+++ b/extensions/diffs/src/browser.runtime.test.ts
@@ -20,7 +20,7 @@ const { launchMock } = vi.hoisted(() => ({
   launchMock: vi.fn(),
 }));
 
-let PlaywrightDiffScreenshotter: typeof import("./browser.js").PlaywrightDiffScreenshotter;
+let PlaywrightDiffScreenshotter: typeof import("./browser.runtime.js").PlaywrightDiffScreenshotter;
 
 vi.mock("playwright-core", () => ({
   chromium: {
@@ -58,7 +58,7 @@ describe("PlaywrightDiffScreenshotter", () => {
       throw new Error("process.platform descriptor is unavailable");
     }
     originalPlatform = platformDescriptor;
-    ({ PlaywrightDiffScreenshotter } = await import("./browser.js"));
+    ({ PlaywrightDiffScreenshotter } = await import("./browser.runtime.js"));
     ({ rootDir, cleanup: cleanupRootDir } = await createTempDiffRoot("openclaw-diffs-browser-"));
     outputPath = path.join(rootDir, "preview.png");
     launchMock.mockReset();
diff --git a/extensions/diffs/src/browser.ts b/extensions/diffs/src/browser.runtime.ts
similarity index 100%
rename from extensions/diffs/src/browser.ts
rename to extensions/diffs/src/browser.runtime.ts
diff --git a/extensions/diffs/src/tool-render-output.test.ts b/extensions/diffs/src/tool-render-output.test.ts
index f5695cd8ad2c..2be1598f4a48 100644
--- a/extensions/diffs/src/tool-render-output.test.ts
+++ b/extensions/diffs/src/tool-render-output.test.ts
@@ -4,7 +4,7 @@ import path from "node:path";
 import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawPluginApi } from "../api.js";
-import type { DiffScreenshotter } from "./browser.js";
+import type { DiffScreenshotter } from "./browser.runtime.js";
 import { resolveDiffsPluginDefaults } from "./config.js";
 import { createDiffStoreHarness } from "./test-helpers.js";
 
diff --git a/extensions/diffs/src/tool.test.ts b/extensions/diffs/src/tool.test.ts
index 4d62fd5efe52..e85d98253335 100644
--- a/extensions/diffs/src/tool.test.ts
+++ b/extensions/diffs/src/tool.test.ts
@@ -4,13 +4,17 @@ import path from "node:path";
 import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "../api.js";
-import type { DiffScreenshotter } from "./browser.js";
+import type { DiffScreenshotter } from "./browser.runtime.js";
 import { resolveDiffsPluginDefaults } from "./config.js";
 import { DiffArtifactStore } from "./store.js";
 import { createDiffStoreHarness } from "./test-helpers.js";
 import { createDiffsTool } from "./tool.js";
 import type { DiffRenderOptions } from "./types.js";
 
+vi.mock("./browser.runtime.js", () => {
+  throw new Error("viewer-only rendering must not load the Playwright renderer");
+});
+
 const DEFAULT_DIFFS_TOOL_DEFAULTS = resolveDiffsPluginDefaults(undefined);
 
 describe("diffs tool", () => {
@@ -342,6 +346,26 @@ describe("diffs tool", () => {
     await expect(fs.readdir(rootDir)).resolves.toEqual([]);
   });
 
+  it("falls back to view output when the default image renderer cannot load", async () => {
+    const tool = createDiffsTool({
+      api: createApi(),
+      store,
+      defaults: DEFAULT_DIFFS_TOOL_DEFAULTS,
+    });
+
+    const result = await tool.execute?.("tool-3b", {
+      before: "one\n",
+      after: "two\n",
+      mode: "both",
+    });
+
+    expect(readTextContent(result, 0)).toContain("Diff viewer ready.");
+    expect((result.details as Record<string, unknown>).viewerUrl).toEqual(expect.any(String));
+    expect((result.details as Record<string, unknown>).fileError).toContain(
+      "viewer-only rendering must not load the Playwright renderer",
+    );
+  });
+
   it("rejects invalid base URLs as tool input errors", async () => {
     const tool = createDiffsTool({
       api: createApi(),
diff --git a/extensions/diffs/src/tool.ts b/extensions/diffs/src/tool.ts
index 8b7756e02ecb..a42c6af74fff 100644
--- a/extensions/diffs/src/tool.ts
+++ b/extensions/diffs/src/tool.ts
@@ -2,6 +2,7 @@
 import fs from "node:fs/promises";
 import { optionalFiniteNumberSchema, stringEnum } from "openclaw/plugin-sdk/channel-actions";
 import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import { createLazyRuntimeModule } from "openclaw/plugin-sdk/lazy-runtime";
 import { readFiniteNumberParam } from "openclaw/plugin-sdk/param-readers";
 import {
   asNonArrayRecord,
@@ -10,7 +11,7 @@ import {
 import { Type } from "typebox";
 import type { Static } from "typebox";
 import type { AnyAgentTool, OpenClawPluginApi, OpenClawPluginToolContext } from "../api.js";
-import { PlaywrightDiffScreenshotter, type DiffScreenshotter } from "./browser.js";
+import type { DiffScreenshotter } from "./browser.runtime.js";
 import { resolveDiffImageRenderOptions } from "./config.js";
 import { DiffRenderInputError, renderDiffDocument } from "./render.js";
 import type { DiffArtifactStore } from "./store.js";
@@ -39,6 +40,7 @@ const MAX_TITLE_BYTES = 1_024;
 const MAX_PATH_BYTES = 2_048;
 const MAX_LANG_BYTES = 128;
 const MAX_DIFF_ARTIFACT_TTL_SECONDS = 21_600;
+const loadDiffsBrowserRuntime = createLazyRuntimeModule(() => import("./browser.runtime.js"));
 
 const DiffsToolSchema = Type.Object(
   {
@@ -125,6 +127,12 @@ export function createDiffsTool(params: {
   screenshotter?: DiffScreenshotter;
   context?: OpenClawPluginToolContext;
 }): AnyAgentTool {
+  const loadScreenshotter = async () =>
+    params.screenshotter ??
+    new (await loadDiffsBrowserRuntime()).PlaywrightDiffScreenshotter({
+      config: params.api.config,
+    });
+
   return {
     name: "diffs",
     label: "Diffs",
@@ -188,10 +196,8 @@ export function createDiffsTool(params: {
         throw error;
       });
 
-      const screenshotter =
-        params.screenshotter ?? new PlaywrightDiffScreenshotter({ config: params.api.config });
-
       if (isArtifactOnlyMode(mode)) {
+        const screenshotter = await loadScreenshotter();
         const artifactFile = await renderDiffArtifactFile({
           screenshotter,
           store: params.store,
@@ -271,6 +277,7 @@ export function createDiffsTool(params: {
       }
 
       try {
+        const screenshotter = await loadScreenshotter();
         const artifactFile = await renderDiffArtifactFile({
           screenshotter,
           store: params.store,

From 8dd21b0f34d29d06b7a44e596efd0a593f03b543 Mon Sep 17 00:00:00 2001
From: Dallin Romney <dallinromney@gmail.com>
Date: Fri, 21 Aug 2026 10:45:18 -0700
Subject: [PATCH 044/124] fix(browser): load Playwright runtime on demand
 (#127049)

* fix(browser): load Playwright runtime on demand

* test(browser): use lazy Playwright accessor

* fix(worker): bind bundled Playwright runtime

* style(worker): format build regression

* style(worker): apply repository formatter
---
 .../playwright-core-bundle.runtime.mjs        |  4 ----
 .../src/browser/playwright-core.runtime.ts    | 21 ++++++++++++-------
 .../pw-download-cancel.chromium.test.ts       | 17 ++++++++-------
 .../src/browser/pw-session-cdp-transport.ts   |  6 ++----
 .../src/browser/pw-session-connection.ts      |  8 ++++---
 .../src/browser/pw-session.mock-setup.ts      |  4 ++--
 .../src/browser/pw-tools-core.state.test.ts   |  2 +-
 .../src/browser/pw-tools-core.state.ts        |  6 ++----
 scripts/lib/worker-deploy-build-plugin.mts    | 10 +++++++++
 .../worker-deploy-build-plugin.test.ts        | 14 +++++++++++++
 10 files changed, 60 insertions(+), 32 deletions(-)
 delete mode 100644 extensions/browser/src/browser/playwright-core-bundle.runtime.mjs

diff --git a/extensions/browser/src/browser/playwright-core-bundle.runtime.mjs b/extensions/browser/src/browser/playwright-core-bundle.runtime.mjs
deleted file mode 100644
index 2f72f1c31712..000000000000
--- a/extensions/browser/src/browser/playwright-core-bundle.runtime.mjs
+++ /dev/null
@@ -1,4 +0,0 @@
-// Build-visible bridge for playwright-core's private User-Agent helper.
-import coreBundle from "playwright-core/lib/coreBundle";
-
-export default coreBundle;
diff --git a/extensions/browser/src/browser/playwright-core.runtime.ts b/extensions/browser/src/browser/playwright-core.runtime.ts
index 14655966ab68..3cd0cf28127f 100644
--- a/extensions/browser/src/browser/playwright-core.runtime.ts
+++ b/extensions/browser/src/browser/playwright-core.runtime.ts
@@ -1,15 +1,22 @@
 /**
  * Playwright runtime loader.
  *
- * Static package imports keep the worker deploy build's executable closure visible
- * to the bundler while normal package builds may still externalize the dependency.
+ * Loads playwright-core only when browser behavior needs it. The worker deploy
+ * build declares its static dependency closure in worker-deploy-build-plugin.mts.
  */
-import playwrightCoreDefault from "playwright-core";
+import { createRequire } from "node:module";
 import type * as PlaywrightCore from "playwright-core";
-import coreBundle from "./playwright-core-bundle.runtime.mjs";
 
-/** Runtime playwright-core module instance. */
-export const playwrightCore = playwrightCoreDefault as typeof PlaywrightCore;
+const require = createRequire(import.meta.url);
+
+/** Loads the Playwright runtime on first Browser use. */
+export function getPlaywrightCore(): typeof PlaywrightCore {
+  return require("playwright-core") as typeof PlaywrightCore;
+}
 
 /** Dependency-owned User-Agent used by Playwright's native CDP WebSocket transport. */
-export const getPlaywrightUserAgent = (coreBundle as { getUserAgent: () => string }).getUserAgent;
+export function getPlaywrightUserAgent(): string {
+  return (
+    require("playwright-core/lib/coreBundle") as { getUserAgent: () => string }
+  ).getUserAgent();
+}
diff --git a/extensions/browser/src/browser/pw-download-cancel.chromium.test.ts b/extensions/browser/src/browser/pw-download-cancel.chromium.test.ts
index ca8c86a89657..494a75c130c4 100644
--- a/extensions/browser/src/browser/pw-download-cancel.chromium.test.ts
+++ b/extensions/browser/src/browser/pw-download-cancel.chromium.test.ts
@@ -4,7 +4,7 @@ import type { AddressInfo } from "node:net";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { useAutoCleanupTempDirTracker } from "../../test-support.js";
-import { playwrightCore } from "./playwright-core.runtime.js";
+import { getPlaywrightCore } from "./playwright-core.runtime.js";
 import { ensurePageState } from "./pw-session-state.js";
 import { closePlaywrightBrowserConnection, getPageForTargetId } from "./pw-session.js";
 import { downloadViaPlaywright, waitForDownloadViaPlaywright } from "./pw-tools-core.downloads.js";
@@ -83,7 +83,7 @@ describe.runIf(runChromiumProof)("managed Chromium download cancellation", () =>
 
     const cdpPort = await getFreePort();
     const profileDir = path.join(rootDir, "profile");
-    const context = await playwrightCore.chromium.launchPersistentContext(profileDir, {
+    const context = await getPlaywrightCore().chromium.launchPersistentContext(profileDir, {
       headless: true,
       executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,
       args: [`--remote-debugging-port=${cdpPort}`],
@@ -222,11 +222,14 @@ describe.runIf(runChromiumProof)("managed Chromium download cancellation", () =>
     await context.close();
 
     const restartedCdpPort = await getFreePort();
-    const restartedContext = await playwrightCore.chromium.launchPersistentContext(profileDir, {
-      headless: true,
-      executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,
-      args: [`--remote-debugging-port=${restartedCdpPort}`],
-    });
+    const restartedContext = await getPlaywrightCore().chromium.launchPersistentContext(
+      profileDir,
+      {
+        headless: true,
+        executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,
+        args: [`--remote-debugging-port=${restartedCdpPort}`],
+      },
+    );
     cleanup.push(async () => await restartedContext.close());
     const restartedPage = restartedContext.pages()[0] ?? (await restartedContext.newPage());
     await restartedPage.goto(`http://127.0.0.1:${downloadPort}/`);
diff --git a/extensions/browser/src/browser/pw-session-cdp-transport.ts b/extensions/browser/src/browser/pw-session-cdp-transport.ts
index f5e9f1828049..9664578ae58e 100644
--- a/extensions/browser/src/browser/pw-session-cdp-transport.ts
+++ b/extensions/browser/src/browser/pw-session-cdp-transport.ts
@@ -4,9 +4,7 @@ import type { Browser, ConnectOverCDPTransport } from "playwright-core";
 import WebSocket from "ws";
 import { formatErrorMessage } from "../infra/errors.js";
 import { openCdpWebSocket } from "./cdp.helpers.js";
-import { playwrightCore } from "./playwright-core.runtime.js";
-
-const { chromium } = playwrightCore;
+import { getPlaywrightCore } from "./playwright-core.runtime.js";
 type CdpSocketLookup = typeof dnsLookupCb;
 
 export async function connectOverCdpPinnedTransport(
@@ -130,7 +128,7 @@ export async function connectOverCdpPinnedTransport(
     ws.on("error", (error) => {
       scheduleTransportClosed(formatErrorMessage(error));
     });
-    return await chromium.connectOverCDP(transport, { timeout: opts.timeout });
+    return await getPlaywrightCore().chromium.connectOverCDP(transport, { timeout: opts.timeout });
   } catch (error) {
     ws.close();
     throw error;
diff --git a/extensions/browser/src/browser/pw-session-connection.ts b/extensions/browser/src/browser/pw-session-connection.ts
index ab62a5384100..ab4d4f03f7b9 100644
--- a/extensions/browser/src/browser/pw-session-connection.ts
+++ b/extensions/browser/src/browser/pw-session-connection.ts
@@ -15,7 +15,7 @@ import {
 } from "./cdp.helpers.js";
 import { getChromeWebSocketEndpoint } from "./chrome.js";
 import { BrowserTabNotFoundError } from "./errors.js";
-import { playwrightCore } from "./playwright-core.runtime.js";
+import { getPlaywrightCore } from "./playwright-core.runtime.js";
 import { connectOverCdpPinnedTransport } from "./pw-session-cdp-transport.js";
 import {
   blockedPageRefsByCdpUrl,
@@ -40,7 +40,6 @@ import {
   targetKey,
 } from "./pw-session-state.js";
 
-const { chromium } = playwrightCore;
 type CdpEndpointPin = NonNullable<Awaited<ReturnType<typeof assertCdpEndpointAllowed>>>;
 
 function resolveCdpConnectRetryDelayMs(attempt: number): number {
@@ -452,7 +451,10 @@ export async function connectBrowser(
                   lookup,
                 });
               }
-              return await chromium.connectOverCDP(connectionUrl, { timeout, headers });
+              return await getPlaywrightCore().chromium.connectOverCDP(connectionUrl, {
+                timeout,
+                headers,
+              });
             }),
           );
         };
diff --git a/extensions/browser/src/browser/pw-session.mock-setup.ts b/extensions/browser/src/browser/pw-session.mock-setup.ts
index 72b389b86127..8f9953d800c5 100644
--- a/extensions/browser/src/browser/pw-session.mock-setup.ts
+++ b/extensions/browser/src/browser/pw-session.mock-setup.ts
@@ -14,12 +14,12 @@ export const getChromeWebSocketEndpointMock: MockFn = vi.fn();
 
 vi.mock("./playwright-core.runtime.js", () => ({
   getPlaywrightUserAgent: () => "Playwright/test",
-  playwrightCore: {
+  getPlaywrightCore: () => ({
     chromium: {
       connectOverCDP: (...args: unknown[]) => connectOverCdpMock(...args),
     },
     devices: {},
-  },
+  }),
 }));
 
 vi.mock("./chrome.js", () => ({
diff --git a/extensions/browser/src/browser/pw-tools-core.state.test.ts b/extensions/browser/src/browser/pw-tools-core.state.test.ts
index c065cfc6e7b0..3d6fb15e0023 100644
--- a/extensions/browser/src/browser/pw-tools-core.state.test.ts
+++ b/extensions/browser/src/browser/pw-tools-core.state.test.ts
@@ -35,7 +35,7 @@ const stateMocks = vi.hoisted(() => ({
 }));
 
 vi.mock("./playwright-core.runtime.js", () => ({
-  playwrightCore: { devices: stateMocks.devices },
+  getPlaywrightCore: () => ({ devices: stateMocks.devices }),
 }));
 
 vi.mock("./pw-session.js", () => ({
diff --git a/extensions/browser/src/browser/pw-tools-core.state.ts b/extensions/browser/src/browser/pw-tools-core.state.ts
index fef272a538dd..7182330ac39c 100644
--- a/extensions/browser/src/browser/pw-tools-core.state.ts
+++ b/extensions/browser/src/browser/pw-tools-core.state.ts
@@ -3,12 +3,10 @@
  */
 import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import type { CDPSession, Page } from "playwright-core";
-import { playwrightCore } from "./playwright-core.runtime.js";
+import { getPlaywrightCore } from "./playwright-core.runtime.js";
 import type { PageState } from "./pw-session-contracts.js";
 import { ensurePageState, getPageForTargetId } from "./pw-session.js";
 
-const { devices: playwrightDevices } = playwrightCore;
-
 type DeviceSize = { width: number; height: number };
 type PageCdpSend = (method: string, params?: Record<string, unknown>) => Promise<unknown>;
 
@@ -252,7 +250,7 @@ export async function setDeviceViaPlaywright(opts: {
   if (!name) {
     throw new Error("device name is required");
   }
-  const descriptor = (playwrightDevices as Record<string, unknown>)[name] as
+  const descriptor = (getPlaywrightCore().devices as Record<string, unknown>)[name] as
     | PlaywrightDeviceDescriptor
     | undefined;
   if (!descriptor) {
diff --git a/scripts/lib/worker-deploy-build-plugin.mts b/scripts/lib/worker-deploy-build-plugin.mts
index a4026c31fc78..501f10e7f365 100644
--- a/scripts/lib/worker-deploy-build-plugin.mts
+++ b/scripts/lib/worker-deploy-build-plugin.mts
@@ -11,6 +11,10 @@ const PLAYWRIGHT_BROWSER_REGISTRY_INIT =
   '    registry = new Registry(require(import_path20.default.join(packageRoot, "browsers.json")));';
 const WORKER_BROWSER_RUNTIME_COMPOSITION = `import { createAttachedBrowserToolRuntime } from "../../extensions/browser/runtime-api.js";
 export default { createAttachedBrowserToolRuntime };`;
+const WORKER_PLAYWRIGHT_RUNTIME = `import * as playwrightCore from "playwright-core";
+import { getUserAgent } from "playwright-core/lib/coreBundle";
+export function getPlaywrightCore() { return playwrightCore; }
+export function getPlaywrightUserAgent() { return getUserAgent(); }`;
 const UNDICI_REQUIRE_BOOTSTRAP = [
   'import { createRequire } from "node:module";',
   "const requireUndici = createRequire(import.meta.url);\n",
@@ -25,6 +29,9 @@ export function createWorkerDeployBuildPlugin(rootDir = process.cwd()) {
   const browserRuntimeBridgePath = fs.realpathSync(
     path.resolve("src/worker/worker-deploy-browser-runtime.ts"),
   );
+  const playwrightRuntimePath = fs.realpathSync(
+    path.resolve("extensions/browser/src/browser/playwright-core.runtime.ts"),
+  );
   const undiciDispatcherOptionsPath = fs.realpathSync(
     path.resolve("src/infra/net/undici-dispatcher-options.ts"),
   );
@@ -55,6 +62,9 @@ export function createWorkerDeployBuildPlugin(rootDir = process.cwd()) {
       if (resolvedId === browserRuntimeBridgePath) {
         return WORKER_BROWSER_RUNTIME_COMPOSITION;
       }
+      if (resolvedId === playwrightRuntimePath) {
+        return WORKER_PLAYWRIGHT_RUNTIME;
+      }
       if (resolvedId === undiciDispatcherOptionsPath) {
         if (UNDICI_REQUIRE_BOOTSTRAP.some((fragment) => !code.includes(fragment))) {
           this.error("undici dispatcher bootstrap changed; update the worker deploy transform");
diff --git a/test/scripts/worker-deploy-build-plugin.test.ts b/test/scripts/worker-deploy-build-plugin.test.ts
index 753403d0f37a..ab6eaa65d16c 100644
--- a/test/scripts/worker-deploy-build-plugin.test.ts
+++ b/test/scripts/worker-deploy-build-plugin.test.ts
@@ -35,6 +35,20 @@ describe("worker deploy build plugin", () => {
     expect(transformed).not.toContain("was not composed by the build");
   });
 
+  it("binds the lazy Playwright accessor to bundled modules", () => {
+    const runtimePath = path.resolve("extensions/browser/src/browser/playwright-core.runtime.ts");
+    const source = fs.readFileSync(runtimePath, "utf8");
+    const plugin = createWorkerDeployBuildPlugin();
+
+    const transformed = plugin.transform.call({ error: fail }, source, runtimePath);
+
+    expect(transformed).toContain('import * as playwrightCore from "playwright-core";');
+    expect(transformed).toContain('import { getUserAgent } from "playwright-core/lib/coreBundle";');
+    expect(transformed).toContain("return playwrightCore;");
+    expect(transformed).not.toContain("createRequire");
+    expect(transformed).not.toContain('require("playwright-core")');
+  });
+
   it("bundles the undici dispatcher dependency without a worker runtime require", () => {
     const dispatcherPath = path.resolve("src/infra/net/undici-dispatcher-options.ts");
     const source = fs.readFileSync(dispatcherPath, "utf8");

From 43c54af3ea90e421a4b16b9bc0d847a13ee7e61d Mon Sep 17 00:00:00 2001
From: Ayaan Zaidi <hi@obviy.us>
Date: Fri, 21 Aug 2026 23:16:04 +0530
Subject: [PATCH 045/124] fix(plugins): bind tool delivery to current turn
 (#127098)

Keep plugin-originated text and media bound to the active host-selected route and revoke authority at turn closure.

Fence Gateway-owned channels until a server-verifiable authority and media-policy contract exists.

Co-authored-by: Ayaan Zaidi <hi@obviy.us>
---
 docs/plugins/building-plugins.md              |  16 +-
 docs/plugins/tool-plugins.md                  |   6 +
 src/agents/agent-tools.ts                     |   2 +
 src/agents/openclaw-plugin-tools.ts           | 153 ++++++++-
 ...w-tools.browser-plugin.integration.test.ts | 293 ++++++++++++++++++
 src/agents/openclaw-tools.plugin-context.ts   |   3 +
 .../tools/gateway.runtime-identity.test.ts    |  43 ++-
 src/agents/tools/gateway.ts                   |   2 +
 .../plugins-core.loader.contract.test.ts      |  20 ++
 src/channels/plugins/registry-loader.ts       |   4 +-
 src/gateway/agent-runtime-identity-token.ts   |  30 +-
 src/gateway/message-action-turn-capability.ts |   2 +
 src/gateway/server-methods/send.test.ts       | 117 +++++++
 src/gateway/server-methods/send.ts            |  20 +-
 src/infra/outbound/deliver-channel.ts         |  49 +--
 src/infra/outbound/deliver-contracts.ts       |   3 +
 src/infra/outbound/deliver-core.ts            |   1 +
 src/infra/outbound/deliver-queue-execute.ts   |   5 +
 src/infra/outbound/deliver.test.ts            |  36 +++
 .../outbound/message-action-contracts.ts      |   6 +
 src/infra/outbound/message-action-runner.ts   |  30 +-
 src/infra/outbound/message-action-send.ts     |  32 +-
 src/infra/outbound/message-gateway-options.ts |   1 +
 src/infra/outbound/message.channels.test.ts   | 115 +++++++
 src/infra/outbound/message.ts                 |  15 +
 src/infra/outbound/outbound-send-service.ts   |  20 +-
 src/plugins/tool-descriptor-cache.test.ts     |  20 ++
 src/plugins/tool-descriptor-cache.ts          |   1 +
 src/plugins/tool-types.ts                     |   7 +
 29 files changed, 974 insertions(+), 78 deletions(-)

diff --git a/docs/plugins/building-plugins.md b/docs/plugins/building-plugins.md
index 2f1b1d381ade..bd5ade6fb546 100644
--- a/docs/plugins/building-plugins.md
+++ b/docs/plugins/building-plugins.md
@@ -244,12 +244,17 @@ loads the owning plugin runtime.
 
 Tool factories receive trusted runtime context, including `deliveryContext`,
 `nativeChannelId` for the active platform conversation when available, and
-`requesterSenderId`.
+`requesterSenderId`. A factory can use
+`toolContext.delivery?.send({ text, mediaUrl })` to send text or media to the
+current conversation. The property is unavailable outside an active channel
+turn or when the channel uses Gateway-owned delivery. OpenClaw binds the route,
+account, thread, and media access policy; the capability expires when the turn
+ends.
 
 ```typescript
 register(api) {
   api.registerTool(
-    {
+    (toolContext) => ({
       name: "workflow_tool",
       description: "Run a workflow",
       parameters: Type.Object({ pipeline: Type.String() }),
@@ -258,13 +263,16 @@ register(api) {
         { additionalProperties: false },
       ),
       async execute(_id, params) {
+        await toolContext.delivery?.send({
+          text: `Workflow started: ${params.pipeline}`,
+        });
         return {
           content: [{ type: "text", text: params.pipeline }],
           details: { pipeline: params.pipeline },
         };
       },
-    },
-    { optional: true },
+    }),
+    { name: "workflow_tool", optional: true },
   );
 }
 ```
diff --git a/docs/plugins/tool-plugins.md b/docs/plugins/tool-plugins.md
index dffa950f9999..814385802fa4 100644
--- a/docs/plugins/tool-plugins.md
+++ b/docs/plugins/tool-plugins.md
@@ -155,6 +155,12 @@ tool({
 });
 ```
 
+Factories can use `toolContext.delivery?.send({ text, mediaUrl })` for outbound
+messages in the active conversation. The host chooses the destination,
+account, thread, and local-media policy; plugins cannot retarget this helper,
+and retained copies stop working after the turn closes. The helper is unavailable
+for channels whose delivery is owned by a Gateway transport.
+
 Factories still declare a fixed tool name up front. Use `definePluginEntry`
 directly when the plugin computes tool names dynamically or combines tools
 with hooks, services, providers, or commands.
diff --git a/src/agents/agent-tools.ts b/src/agents/agent-tools.ts
index e9832ebeb125..59f0c5e5a3d6 100644
--- a/src/agents/agent-tools.ts
+++ b/src/agents/agent-tools.ts
@@ -700,6 +700,7 @@ function createOpenClawCodingToolsInternal(options?: OpenClawCodingToolsOptions)
       : resolveOpenClawPluginToolsForOptions({
           options: {
             agentSessionKey: options?.sessionKey,
+            runId: options?.runId,
             agentChannel: resolveGatewayMessageChannel(
               options?.messageChannel ?? options?.messageProvider,
             ),
@@ -707,6 +708,7 @@ function createOpenClawCodingToolsInternal(options?: OpenClawCodingToolsOptions)
             agentTo: options?.messageTo,
             agentThreadId: options?.messageThreadId,
             nativeChannelId: options?.nativeChannelId,
+            messageActionTurnCapability: options?.messageActionTurnCapability,
             agentDir: options?.agentDir,
             preparedModelRuntime: options?.preparedModelRuntime,
             workspaceDir: workspaceRoot,
diff --git a/src/agents/openclaw-plugin-tools.ts b/src/agents/openclaw-plugin-tools.ts
index 97ffe0f9f8a3..1d46b8ac7905 100644
--- a/src/agents/openclaw-plugin-tools.ts
+++ b/src/agents/openclaw-plugin-tools.ts
@@ -5,9 +5,20 @@
  * auth profiles, and the current runtime config snapshot.
  */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
-import { getActivePluginRegistry } from "../plugins/runtime.js";
-import { getPluginRuntimeGatewayRequestScope } from "../plugins/runtime/gateway-request-scope.js";
+import {
+  resolveMessageActionTurnCapability,
+  selectMessageActionRequesterIdentity,
+} from "../gateway/message-action-turn-capability.js";
+import { resolveAgentScopedOutboundMediaAccess } from "../media/read-capability.js";
+import { getActivePluginRegistry, getActivePluginRegistryVersion } from "../plugins/runtime.js";
+import {
+  getPluginRuntimeGatewayRequestScope,
+  withPluginRuntimeRegistryScope,
+} from "../plugins/runtime/gateway-request-scope.js";
+import type { OpenClawPluginToolDelivery } from "../plugins/tool-types.js";
 import { resolvePluginTools } from "../plugins/tools.js";
+import type { OpenClawPluginToolContext } from "../plugins/types.js";
+import { createLazyRuntimeModule } from "../shared/lazy-runtime.js";
 import { resolveApiKeyForProfile, resolveAuthProfileOrder } from "./auth-profiles.js";
 import type { AuthProfileStore } from "./auth-profiles/types.js";
 import {
@@ -46,6 +57,137 @@ type ResolveOpenClawPluginToolsOptions = OpenClawPluginToolOptions & {
   authProfileStore?: AuthProfileStore;
 };
 
+const loadMessageActionRunner = createLazyRuntimeModule(
+  () => import("../infra/outbound/message-action-runner.js"),
+);
+
+function createPluginToolDelivery(params: {
+  options: ResolveOpenClawPluginToolsOptions | undefined;
+  context: OpenClawPluginToolContext;
+  bindingConfig: OpenClawConfig | undefined;
+  resolveConfig: () => OpenClawConfig | undefined;
+}): OpenClawPluginToolDelivery | undefined {
+  const deliveryContext = params.context.deliveryContext;
+  const agentId = params.context.agentId;
+  const sessionKey = params.context.sessionKey;
+  const sessionId = params.context.sessionId;
+  const senderIsOwner = params.context.senderIsOwner;
+  const conversationReadOrigin = params.context.conversationReadOrigin;
+  const runId = params.options?.runId;
+  const token = params.options?.messageActionTurnCapability;
+  const activeRegistry = getActivePluginRegistry();
+  const activeRegistryVersion = getActivePluginRegistryVersion();
+  if (
+    !deliveryContext?.channel ||
+    !deliveryContext.to ||
+    !agentId ||
+    !sessionKey ||
+    !runId ||
+    !token ||
+    !activeRegistry
+  ) {
+    return undefined;
+  }
+  const channelPlugin = activeRegistry.channels.find(
+    (entry) => entry.plugin.id === deliveryContext.channel,
+  )?.plugin;
+  // The turn capability and sender-scoped media reader are process-local.
+  // Gateway-owned delivery needs a server-verifiable authority contract first.
+  if (channelPlugin?.outbound?.deliveryMode === "gateway") {
+    return undefined;
+  }
+  const route = {
+    channel: deliveryContext.channel,
+    to: deliveryContext.to,
+    accountId: deliveryContext.accountId,
+    threadId: deliveryContext.threadId,
+  };
+
+  const resolveAuthorization = () => {
+    if (
+      getActivePluginRegistry() !== activeRegistry ||
+      getActivePluginRegistryVersion() !== activeRegistryVersion
+    ) {
+      throw new Error("plugin delivery capability is no longer active");
+    }
+    const authorization = resolveMessageActionTurnCapability({
+      token,
+      agentId,
+      runId,
+      sessionKey,
+      sessionId,
+    });
+    if (!authorization) {
+      throw new Error("plugin delivery capability is no longer active");
+    }
+    return authorization;
+  };
+  const bindingAuthorization = resolveAuthorization();
+  const bindingConfig = params.bindingConfig;
+  if (!bindingConfig) {
+    return undefined;
+  }
+  const mediaAccess = resolveAgentScopedOutboundMediaAccess({
+    cfg: bindingConfig,
+    agentId,
+    workspaceDir: params.context.workspaceDir,
+    sessionKey,
+    accountId: bindingAuthorization.requesterAccountId ?? route.accountId,
+    requesterSenderId: bindingAuthorization.requesterSenderId,
+    requesterSenderName: bindingAuthorization.requesterSenderName,
+    requesterSenderUsername: bindingAuthorization.requesterSenderUsername,
+    requesterSenderE164: bindingAuthorization.requesterSenderE164,
+  });
+
+  return {
+    send: async ({ text, mediaUrl }) => {
+      resolveAuthorization();
+      const { runMessageAction } = await loadMessageActionRunner();
+      const authorization = resolveAuthorization();
+      const cfg = params.resolveConfig();
+      if (!cfg) {
+        throw new Error("plugin delivery requires an active runtime config");
+      }
+      await withPluginRuntimeRegistryScope(activeRegistry, () =>
+        runMessageAction({
+          cfg,
+          action: "send",
+          params: {
+            channel: route.channel,
+            target: route.to,
+            ...(route.accountId ? { accountId: route.accountId } : {}),
+            ...(route.threadId != null ? { threadId: route.threadId } : {}),
+            ...(text !== undefined ? { message: text } : {}),
+            ...(mediaUrl !== undefined ? { mediaUrl } : {}),
+          },
+          defaultAccountId: route.accountId,
+          ...selectMessageActionRequesterIdentity(authorization),
+          messageActionAuthorization: {
+            requesterAccountId: authorization.requesterAccountId,
+            requesterSenderId: authorization.requesterSenderId,
+            toolContext: authorization.toolContext,
+          },
+          senderIsOwner,
+          conversationReadOrigin,
+          toolContext: authorization.toolContext,
+          sessionKey,
+          sessionId,
+          runId,
+          agentId,
+          mediaAccess,
+          onPlatformSendDispatch: async () => {
+            resolveAuthorization();
+          },
+          forceCoreDelivery: true,
+          skipQueue: true,
+          dryRun: false,
+        }),
+      );
+      resolveAuthorization();
+    },
+  };
+}
+
 /** Resolves plugin tools for an agent run and applies delivery-context defaults. */
 export function resolveOpenClawPluginToolsForOptions(params: {
   options?: ResolveOpenClawPluginToolsOptions;
@@ -69,6 +211,12 @@ export function resolveOpenClawPluginToolsForOptions(params: {
   });
   const authProfileStore = params.options?.authProfileStore;
   const availabilityConfig = resolveCurrentRuntimeConfig();
+  const delivery = createPluginToolDelivery({
+    options: params.options,
+    context: pluginToolInputs.context,
+    bindingConfig: availabilityConfig,
+    resolveConfig: resolveCurrentRuntimeConfig,
+  });
   const availabilityRuntimeLookup = authProfileStore
     ? createRuntimeProviderAuthLookup({
         cfg: availabilityConfig,
@@ -146,6 +294,7 @@ export function resolveOpenClawPluginToolsForOptions(params: {
     ...pluginToolInputs,
     context: {
       ...pluginToolInputs.context,
+      ...(delivery ? { delivery } : {}),
       ...(hasAuthForProvider ? { hasAuthForProvider } : {}),
       ...(resolveApiKeyForProvider ? { resolveApiKeyForProvider } : {}),
     },
diff --git a/src/agents/openclaw-tools.browser-plugin.integration.test.ts b/src/agents/openclaw-tools.browser-plugin.integration.test.ts
index febf4804bf17..09cbbed7372e 100644
--- a/src/agents/openclaw-tools.browser-plugin.integration.test.ts
+++ b/src/agents/openclaw-tools.browser-plugin.integration.test.ts
@@ -1,16 +1,26 @@
 // Verifies OpenClaw plugin tools are resolved with browser/runtime context.
+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 { createDeferred } from "../../test/helpers/promise.js";
 import type { OpenClawConfig } from "../config/config.js";
 import { resetConfigRuntimeState, setRuntimeConfigSnapshot } from "../config/config.js";
 import {
   createPluginMetadataSnapshot,
   makeRegistry,
 } from "../config/plugin-auto-enable.test-helpers.js";
+import {
+  mintMessageActionTurnCapability,
+  revokeMessageActionTurnCapability,
+} from "../gateway/message-action-turn-capability.js";
+import { buildOutboundMediaLoadOptions } from "../media/load-options.js";
+import { loadWebMediaRaw } from "../media/web-media.js";
 import { createEmptyPluginRegistry } from "../plugins/registry-empty.js";
 import { resetPluginRuntimeStateForTest, setActivePluginRegistry } from "../plugins/runtime.js";
+import { withPluginRuntimeRegistryScope } from "../plugins/runtime/gateway-request-scope.js";
 import { activateSecretsRuntimeSnapshot, clearSecretsRuntimeSnapshot } from "../secrets/runtime.js";
+import { createOutboundTestPlugin, createTestRegistry } from "../test-utils/channel-plugins.js";
 import { getRuntimeAuthProfileStoreCredentialsRevision } from "./auth-profiles/runtime-snapshots.js";
 import { resolveOpenClawPluginToolsForOptions } from "./openclaw-plugin-tools.js";
 import { createOpenClawTools } from "./openclaw-tools.js";
@@ -18,6 +28,7 @@ import {
   getPreparedPluginRuntimeLoadContext,
   prepareOwnedPluginLoadContext,
 } from "./prepared-model-runtime.plugin-context.js";
+import { jsonResult } from "./tools/common.js";
 
 const hoisted = vi.hoisted(() => ({
   resolvePluginTools: vi.fn(),
@@ -150,6 +161,288 @@ describe("createOpenClawTools browser plugin integration", () => {
     expect(details.workspaceOnly).toBe(true);
   });
 
+  it("binds plugin delivery to the current route, media roots, and turn lifetime", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-plugin-delivery-"));
+    const mediaUrl = path.join(workspaceDir, "photo.png");
+    const outsideMediaUrl = `${workspaceDir}-outside.png`;
+    await fs.copyFile(
+      path.join(
+        process.cwd(),
+        "apps/ios/WatchApp/Assets.xcassets/OpenClawIcon.imageset/openclaw-icon.png",
+      ),
+      mediaUrl,
+    );
+    await fs.copyFile(mediaUrl, outsideMediaUrl);
+    const platformSendMedia = vi.fn(async () => ({ channel: "telegram", messageId: "sent-1" }));
+    const transportDispatchStarted = createDeferred();
+    const resumeTransportDispatch = createDeferred();
+    let deferTransportDispatch = false;
+    const sendMedia = vi.fn(
+      async (params: {
+        mediaLocalRoots?: readonly string[];
+        mediaReadFile?: (filePath: string) => Promise<Buffer>;
+        mediaUrl?: string;
+        onPlatformSendDispatch?: () => Promise<void>;
+      }) => {
+        if (deferTransportDispatch) {
+          transportDispatchStarted.resolve();
+          await resumeTransportDispatch.promise;
+        }
+        if (params.mediaUrl) {
+          await loadWebMediaRaw(
+            params.mediaUrl,
+            buildOutboundMediaLoadOptions({
+              mediaLocalRoots: params.mediaLocalRoots,
+              mediaReadFile: params.mediaReadFile,
+            }),
+          );
+        }
+        await params.onPlatformSendDispatch?.();
+        return await platformSendMedia();
+      },
+    );
+    const providerNativeSend = vi.fn(async () => jsonResult({ ok: true, native: true }));
+    const telegramPlugin = createOutboundTestPlugin({
+      id: "telegram",
+      outbound: {
+        deliveryMode: "direct",
+        sendText: async () => ({ channel: "telegram", messageId: "text-1" }),
+        sendMedia,
+      },
+      messaging: {
+        normalizeTarget: (raw) => raw,
+        targetResolver: {
+          looksLikeId: () => true,
+          hint: "<chat-id>",
+        },
+      },
+    });
+    telegramPlugin.actions = {
+      describeMessageTool: () => null,
+      handleAction: providerNativeSend,
+    };
+    const activeRegistry = createTestRegistry([
+      {
+        pluginId: "telegram",
+        source: "test",
+        plugin: {
+          ...telegramPlugin,
+          config: {
+            ...telegramPlugin.config,
+            listAccountIds: () => ["work", "attacker-account"],
+            resolveAccount: () => ({}),
+          },
+        },
+      },
+    ]);
+    setActivePluginRegistry(activeRegistry);
+    const turnCapability = mintMessageActionTurnCapability({
+      agentId: "main",
+      runId: "run-1",
+      sessionKey: "agent:main:telegram:group:123",
+      sessionId: "session-1",
+      requesterAccountId: "work",
+      requesterSenderId: "sender-1",
+      toolContext: {
+        currentChannelId: "123",
+        currentMessagingTarget: "123",
+        currentChannelProvider: "telegram",
+        currentThreadTs: "7",
+      },
+    });
+    const config = {
+      agents: { defaults: { workspace: workspaceDir } },
+      channels: { telegram: { enabled: true } },
+      plugins: { allow: ["telegram"] },
+      tools: { fs: { workspaceOnly: true } },
+    } as OpenClawConfig;
+    let delivery:
+      | {
+          send: (params: { text: string; mediaUrl?: string }) => Promise<void>;
+        }
+      | undefined;
+    hoisted.resolvePluginTools.mockImplementation((params: unknown) => {
+      const context = (
+        params as {
+          context?: {
+            deliveryContext?: {
+              to?: string;
+              accountId?: string;
+              threadId?: string | number;
+            };
+            delivery?: {
+              send: (sendParams: { text: string; mediaUrl?: string }) => Promise<void>;
+            };
+          };
+        }
+      ).context;
+      delivery = context?.delivery;
+      if (context?.deliveryContext) {
+        context.deliveryContext.to = "attacker-chat";
+        context.deliveryContext.accountId = "attacker-account";
+        context.deliveryContext.threadId = "attacker-thread";
+      }
+      config.tools = { allow: ["read"], fs: { workspaceOnly: false } };
+      return [];
+    });
+    let nextTurnCapability: string | undefined;
+
+    try {
+      createOpenClawTools({
+        config,
+        agentSessionKey: "agent:main:telegram:group:123",
+        runId: "run-1",
+        sessionId: "session-1",
+        agentChannel: "telegram",
+        agentAccountId: "work",
+        agentTo: "123",
+        agentThreadId: "7",
+        workspaceDir,
+        requesterAgentIdOverride: "main",
+        messageActionTurnCapability: turnCapability,
+        disableMessageTool: true,
+      });
+
+      if (!delivery) {
+        throw new Error("expected plugin delivery capability");
+      }
+      const activeDelivery = delivery;
+      await withPluginRuntimeRegistryScope(createEmptyPluginRegistry(), () =>
+        activeDelivery.send({ text: "bound media", mediaUrl }),
+      );
+      expect(sendMedia).toHaveBeenCalledWith(
+        expect.objectContaining({
+          to: "123",
+          text: "bound media",
+          accountId: "work",
+          threadId: "7",
+          mediaLocalRoots: expect.arrayContaining([workspaceDir]),
+        }),
+      );
+      expect(providerNativeSend).not.toHaveBeenCalled();
+      await expect(
+        activeDelivery.send({ text: "outside media", mediaUrl: outsideMediaUrl }),
+      ).rejects.toThrow(/not under an allowed directory/i);
+      expect(platformSendMedia).toHaveBeenCalledOnce();
+
+      deferTransportDispatch = true;
+      const pending = withPluginRuntimeRegistryScope(createEmptyPluginRegistry(), () =>
+        activeDelivery.send({ text: "closing", mediaUrl }),
+      );
+      await transportDispatchStarted.promise;
+      revokeMessageActionTurnCapability(turnCapability);
+      resumeTransportDispatch.resolve();
+      await expect(pending).rejects.toThrow("plugin delivery capability is no longer active");
+      expect(platformSendMedia).toHaveBeenCalledTimes(1);
+      expect(providerNativeSend).not.toHaveBeenCalled();
+      await expect(activeDelivery.send({ text: "too late" })).rejects.toThrow(
+        "plugin delivery capability is no longer active",
+      );
+      expect(platformSendMedia).toHaveBeenCalledTimes(1);
+
+      nextTurnCapability = mintMessageActionTurnCapability({
+        agentId: "main",
+        runId: "run-2",
+        sessionKey: "agent:main:telegram:group:123",
+        sessionId: "session-2",
+      });
+      createOpenClawTools({
+        config,
+        agentSessionKey: "agent:main:telegram:group:123",
+        runId: "run-2",
+        sessionId: "session-2",
+        agentChannel: "telegram",
+        agentAccountId: "work",
+        agentTo: "123",
+        workspaceDir,
+        requesterAgentIdOverride: "main",
+        messageActionTurnCapability: nextTurnCapability,
+        disableMessageTool: true,
+      });
+      if (!delivery) {
+        throw new Error("expected replacement plugin delivery capability");
+      }
+      const replacementDelivery = delivery;
+      setActivePluginRegistry(createEmptyPluginRegistry());
+      await expect(replacementDelivery.send({ text: "stale registry" })).rejects.toThrow(
+        "plugin delivery capability is no longer active",
+      );
+      setActivePluginRegistry(activeRegistry);
+      await expect(replacementDelivery.send({ text: "reactivated registry" })).rejects.toThrow(
+        "plugin delivery capability is no longer active",
+      );
+    } finally {
+      revokeMessageActionTurnCapability(turnCapability);
+      revokeMessageActionTurnCapability(nextTurnCapability);
+      await fs.rm(workspaceDir, { recursive: true, force: true });
+      await fs.rm(outsideMediaUrl, { force: true });
+    }
+  });
+
+  it("does not expose plugin delivery without a host turn capability", () => {
+    hoisted.resolvePluginTools.mockReturnValue([]);
+    setActivePluginRegistry(createEmptyPluginRegistry());
+
+    resolveOpenClawPluginToolsForOptions({
+      options: {
+        config: {} as OpenClawConfig,
+        agentSessionKey: "agent:main:telegram:group:123",
+        runId: "run-1",
+        sessionId: "session-1",
+        agentChannel: "telegram",
+        agentAccountId: "work",
+        agentTo: "123",
+        requesterAgentIdOverride: "main",
+      },
+      resolvedConfig: {} as OpenClawConfig,
+    });
+
+    expect(
+      (firstResolvePluginToolsParams().context as { delivery?: unknown } | undefined)?.delivery,
+    ).toBeUndefined();
+  });
+
+  it("does not expose process-local plugin delivery to gateway-owned channels", () => {
+    const gatewayPlugin = createOutboundTestPlugin({
+      id: "gatewaychat",
+      outbound: { deliveryMode: "gateway" },
+    });
+    setActivePluginRegistry(
+      createTestRegistry([{ pluginId: "gatewaychat", source: "test", plugin: gatewayPlugin }]),
+    );
+    const turnCapability = mintMessageActionTurnCapability({
+      agentId: "main",
+      runId: "run-1",
+      sessionKey: "agent:main:gatewaychat:direct:123",
+      sessionId: "session-1",
+      requesterSenderId: "sender-1",
+    });
+    const config = {
+      gateway: { mode: "remote", remote: { url: "wss://gateway.example" } },
+    } as OpenClawConfig;
+
+    try {
+      hoisted.resolvePluginTools.mockReturnValue([]);
+      createOpenClawTools({
+        config,
+        agentSessionKey: "agent:main:gatewaychat:direct:123",
+        runId: "run-1",
+        sessionId: "session-1",
+        agentChannel: "gatewaychat",
+        agentTo: "123",
+        requesterAgentIdOverride: "main",
+        messageActionTurnCapability: turnCapability,
+        disableMessageTool: true,
+      });
+
+      expect(
+        (firstResolvePluginToolsParams().context as { delivery?: unknown } | undefined)?.delivery,
+      ).toBeUndefined();
+    } finally {
+      revokeMessageActionTurnCapability(turnCapability);
+    }
+  });
+
   it("forwards gateway subagent binding to plugin resolution", () => {
     hoisted.resolvePluginTools.mockReturnValue([]);
     const config = {
diff --git a/src/agents/openclaw-tools.plugin-context.ts b/src/agents/openclaw-tools.plugin-context.ts
index df7bcb20dae0..c61195bde0a1 100644
--- a/src/agents/openclaw-tools.plugin-context.ts
+++ b/src/agents/openclaw-tools.plugin-context.ts
@@ -18,6 +18,7 @@ import { resolveWorkspaceRoot } from "./workspace-dir.js";
 /** Options provided by agent runtime callers when invoking OpenClaw plugin tools. */
 export type OpenClawPluginToolOptions = {
   agentSessionKey?: string;
+  runId?: string;
   agentChannel?: string;
   agentAccountId?: string;
   agentTo?: string;
@@ -27,6 +28,8 @@ export type OpenClawPluginToolOptions = {
   currentChannelId?: string;
   agentThreadId?: string | number;
   nativeChannelId?: string;
+  /** Opaque host-issued capability for current-turn channel message actions. */
+  messageActionTurnCapability?: string;
   agentDir?: string;
   workspaceDir?: string;
   config?: OpenClawConfig;
diff --git a/src/agents/tools/gateway.runtime-identity.test.ts b/src/agents/tools/gateway.runtime-identity.test.ts
index e78db39be646..df3f60d5a4d4 100644
--- a/src/agents/tools/gateway.runtime-identity.test.ts
+++ b/src/agents/tools/gateway.runtime-identity.test.ts
@@ -2,7 +2,10 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createExecutionIdentityAdmissionToken } from "../../audit/execution-identity-admission.js";
 import { withAgentRuntimeExecutionLineage } from "../../gateway/agent-runtime-execution-lineage.js";
-import { verifyAgentRuntimeIdentityToken } from "../../gateway/agent-runtime-identity-token.js";
+import {
+  createAgentRuntimeApprovalAuthorityValidator,
+  verifyAgentRuntimeIdentityToken,
+} from "../../gateway/agent-runtime-identity-token.js";
 import { resolveExecutionIdentitySpawnFacts } from "../../gateway/agent-turn/agent-run-execution-lineage.js";
 import type { CallGatewayOptions } from "../../gateway/call.js";
 import {
@@ -361,6 +364,44 @@ describe("gateway tool runtime identity", () => {
     ).rejects.toThrow("terminal source reply requires trusted agent runtime identity");
   });
 
+  it("invalidates message action identity when its turn capability closes", async () => {
+    const operationalRunInstance = createOperationalRunInstanceRef("run-capability-close");
+    const sessionKey = "agent:ops:telegram:group:room-close";
+    const turnCapability = mintMessageActionTurnCapability({
+      agentId: "ops",
+      runId: operationalRunInstance.runId,
+      sessionKey,
+      sessionId: "session-capability-close",
+    });
+    mintedTurnCapabilities.push(turnCapability);
+
+    await withActiveGatewayToolCallerIdentity(
+      { agentId: "ops", sessionKey, operationalRunInstance },
+      async () => {
+        const token = await resolveMessageActionAgentRuntimeIdentityToken({
+          opts: {},
+          target: "local",
+          turnCapability,
+          runId: operationalRunInstance.runId,
+          sessionId: "session-capability-close",
+        });
+        const identity = await verifyAgentRuntimeIdentityToken(token);
+        expect(identity).toMatchObject({
+          messageActionContext: { turnCapability },
+        });
+        expect(identity).toBeDefined();
+        if (!identity) {
+          return;
+        }
+        const validate = createAgentRuntimeApprovalAuthorityValidator();
+        expect(validate(identity)).toBe(true);
+
+        expect(revokeMessageActionTurnCapability(turnCapability)).toBe(true);
+        expect(validate(identity)).toBe(false);
+      },
+    );
+  });
+
   it("mints split-session message action identity and rejects policy-session substitution", async () => {
     const policySessionKey = "agent:ops:telegram:default:direct:alice";
     const runSessionKey = "agent:ops:main";
diff --git a/src/agents/tools/gateway.ts b/src/agents/tools/gateway.ts
index a20926ee0797..8d36ff2ef42e 100644
--- a/src/agents/tools/gateway.ts
+++ b/src/agents/tools/gateway.ts
@@ -503,11 +503,13 @@ export async function resolveMessageActionAgentRuntimeIdentityToken(params: {
   const resolvedMessageActionContext = terminalSourceReply
     ? {
         ...messageActionContext,
+        turnCapability: params.turnCapability,
         sourceReplyFinal: true as const,
         sourceReplyToolCallId: sourceReplyToolCallId!,
       }
     : {
         ...messageActionContext,
+        turnCapability: params.turnCapability,
         ...(params.sourceReplyFinal === false ? { sourceReplyFinal: false as const } : {}),
         ...(sourceReplyToolCallId ? { sourceReplyToolCallId } : {}),
       };
diff --git a/src/channels/plugins/contracts/plugins-core.loader.contract.test.ts b/src/channels/plugins/contracts/plugins-core.loader.contract.test.ts
index fcaa45c0eeec..23dc6727a153 100644
--- a/src/channels/plugins/contracts/plugins-core.loader.contract.test.ts
+++ b/src/channels/plugins/contracts/plugins-core.loader.contract.test.ts
@@ -114,6 +114,26 @@ describe("channel plugin loader", () => {
     expect(loaded).toBe(demoOutbound);
   });
 
+  it("does not escape the scoped registry when the channel is omitted", async () => {
+    setActivePluginRegistry(registryWithDemoLoader);
+
+    const loaded = await withPluginRuntimeRegistryScope(emptyRegistry, () =>
+      loadChannelOutboundAdapter("demo-loader"),
+    );
+
+    expect(loaded).toBeUndefined();
+  });
+
+  it("preserves a missing adapter from the scoped channel registration", async () => {
+    setActivePluginRegistry(registryWithDemoLoader);
+
+    const loaded = await withPluginRuntimeRegistryScope(registryWithDemoLoaderNoOutbound, () =>
+      loadChannelOutboundAdapter("demo-loader"),
+    );
+
+    expect(loaded).toBeUndefined();
+  });
+
   it.each([
     {
       name: "loads channel plugins from the active registry",
diff --git a/src/channels/plugins/registry-loader.ts b/src/channels/plugins/registry-loader.ts
index 3bb60f21b78b..b250a6a945dc 100644
--- a/src/channels/plugins/registry-loader.ts
+++ b/src/channels/plugins/registry-loader.ts
@@ -1,7 +1,7 @@
 /**
  * Lazy channel registry value loader.
  *
- * Resolves plugin sub-surfaces from the process-root registry.
+ * Resolves plugin sub-surfaces from the request-scoped or process-root registry.
  */
 import type { PluginChannelRegistration } from "../../plugins/registry-types.js";
 import { getActivePluginRegistry } from "../../plugins/runtime.js";
@@ -13,7 +13,7 @@ type ChannelRegistryValueResolver<TValue> = (
 ) => TValue | undefined;
 
 /**
- * Creates a lazy loader that resolves one value from the active channel registry.
+ * Creates a lazy loader that resolves one value from the authoritative channel registry.
  */
 export function createChannelRegistryLoader<TValue>(
   resolveValue: ChannelRegistryValueResolver<TValue>,
diff --git a/src/gateway/agent-runtime-identity-token.ts b/src/gateway/agent-runtime-identity-token.ts
index 403155d2dcf1..6a9f0972c0bd 100644
--- a/src/gateway/agent-runtime-identity-token.ts
+++ b/src/gateway/agent-runtime-identity-token.ts
@@ -25,7 +25,10 @@ import {
 } from "./agent-runtime-execution-lineage.js";
 import type { AgentRuntimeSessionSpawnContext } from "./agent-runtime-session-spawn-context.js";
 import type { CronCreatorAuthorityGrant } from "./cron-creator-authority-grant.js";
-import type { AgentRuntimeMessageActionContext } from "./message-action-turn-capability.js";
+import {
+  resolveMessageActionTurnCapability,
+  type AgentRuntimeMessageActionContext,
+} from "./message-action-turn-capability.js";
 import type { WorkerSessionTurnClaim } from "./worker-environments/placement-record.js";
 
 const AGENT_RUNTIME_IDENTITY_TOKEN_CONTEXT = "openclaw:gateway-agent-runtime-identity-token:v1";
@@ -192,6 +195,7 @@ const messageActionToolContextSchema = z
   );
 const messageActionContextSchema = z.object({
   expiresAtMs: z.number().finite(),
+  turnCapability: normalizedRequiredStringSchema.optional(),
   sourceReplyFinal: z.boolean().optional(),
   sourceReplyToolCallId: normalizedRequiredStringSchema.optional(),
   sessionId: ignoredOptionalStringSchema,
@@ -290,6 +294,7 @@ function decodeMessageActionContext(
   }
   const context = {
     expiresAtMs: value.expiresAtMs,
+    turnCapability: value.turnCapability,
     sessionId: value.sessionId,
     sourceReplySessionKey: value.sourceReplySessionKey,
     requesterAccountId: value.requesterAccountId,
@@ -648,6 +653,25 @@ function validateAgentRuntimeDelegatedAuthority(
 export function createAgentRuntimeApprovalAuthorityValidator(
   placements?: WorkerTurnClaimValidator,
 ): AgentRuntimeApprovalAuthorityValidator {
-  return (identity) =>
-    validateAgentRuntimeDelegatedAuthority(identity.delegatedAuthority, placements);
+  return (identity) => {
+    if (!validateAgentRuntimeDelegatedAuthority(identity.delegatedAuthority, placements)) {
+      return false;
+    }
+    const messageActionContext = identity.messageActionContext;
+    if (!messageActionContext) {
+      return true;
+    }
+    if (!messageActionContext.turnCapability) {
+      return false;
+    }
+    return Boolean(
+      resolveMessageActionTurnCapability({
+        token: messageActionContext.turnCapability,
+        agentId: identity.agentId,
+        runId: identity.operationalRunInstance.runId,
+        sessionKey: identity.sessionKey,
+        sessionId: messageActionContext.sessionId,
+      }),
+    );
+  };
 }
diff --git a/src/gateway/message-action-turn-capability.ts b/src/gateway/message-action-turn-capability.ts
index fa6811e2b03c..00ccf34be2e7 100644
--- a/src/gateway/message-action-turn-capability.ts
+++ b/src/gateway/message-action-turn-capability.ts
@@ -24,6 +24,8 @@ type MessageActionRequesterIdentity = {
 
 type AgentRuntimeMessageActionContextBase = MessageActionRequesterIdentity & {
   expiresAtMs: number;
+  /** Process-local owner reference revalidated before privileged Gateway use. */
+  turnCapability?: string;
   sessionId?: string;
   /** Durable session entry that owns restart-recovery receipt state. */
   sourceReplySessionKey?: string;
diff --git a/src/gateway/server-methods/send.test.ts b/src/gateway/server-methods/send.test.ts
index b583489bea9d..6828e4a1fb6c 100644
--- a/src/gateway/server-methods/send.test.ts
+++ b/src/gateway/server-methods/send.test.ts
@@ -11,9 +11,14 @@ import {
 } from "../../../packages/gateway-protocol/src/client-info.js";
 import { ErrorCodes } from "../../../packages/gateway-protocol/src/index.js";
 import { createDeferred } from "../../../test/helpers/promise.js";
+import { createOperationalRunInstanceRef } from "../../agents/admitted-run-context.js";
 import { jsonResult } from "../../agents/tools/common.js";
 import type { ChannelPlugin } from "../../channels/plugins/types.public.js";
 import type { SessionTranscriptAppendResult } from "../../config/sessions/transcript.js";
+import {
+  claimAgentRunDelegatedAuthority,
+  releaseAgentRunDelegatedAuthority,
+} from "../../infra/agent-run-registry.js";
 import { buildOutboundMediaLoadOptions } from "../../media/load-options.js";
 import { loadWebMediaRaw } from "../../media/web-media.js";
 import { resetPluginRuntimeStateForTest, setActivePluginRegistry } from "../../plugins/runtime.js";
@@ -23,6 +28,11 @@ import {
   createTestRegistry,
 } from "../../test-utils/channel-plugins.js";
 import { captureEnv, setTestEnvValue } from "../../test-utils/env.js";
+import { createAgentRuntimeApprovalAuthorityValidator } from "../agent-runtime-identity-token.js";
+import {
+  mintMessageActionTurnCapability,
+  revokeMessageActionTurnCapability,
+} from "../message-action-turn-capability.js";
 import { DEDUPE_MAX, DEDUPE_TTL_MS } from "../server-constants.js";
 import { startGatewayMaintenanceTimers } from "../server-maintenance.js";
 import { createGatewayMaintenanceStateForTest } from "../test-helpers.maintenance-state.js";
@@ -1446,6 +1456,113 @@ describe("gateway send mirroring", () => {
     expect(mocks.ensureOutboundSessionEntry).not.toHaveBeenCalled();
   });
 
+  it("does not send or queue after delegated authority closes during delivery preflight", async () => {
+    const enteredDelivery = createDeferred<null>();
+    const resumeDelivery = createDeferred<null>();
+    const platformSend = vi.fn();
+    mocks.deliverOutboundPayloads.mockImplementationOnce(
+      async (params: { onPlatformSendDispatch?: () => Promise<void> }) => {
+        enteredDelivery.resolve(null);
+        await resumeDelivery.promise;
+        await params.onPlatformSendDispatch?.();
+        platformSend();
+        return [{ channel: "slack", messageId: "must-not-send" }];
+      },
+    );
+    let authorityActive = true;
+    const context = {
+      ...makeContext(),
+      validateAgentRuntimeApprovalAuthority: () => authorityActive,
+    } as GatewayRequestContext;
+    const request = runSendWithClient(
+      {
+        channel: "slack",
+        to: "channel:C1",
+        message: "must not escape",
+        sessionKey: "agent:main:slack:channel:C1",
+        idempotencyKey: "idem-send-delivery-authority-race",
+      },
+      agentRuntimeClient("agent:main:slack:channel:C1"),
+      context,
+    );
+    await enteredDelivery.promise;
+    authorityActive = false;
+    resumeDelivery.resolve(null);
+
+    const { respond } = await request;
+    expect(firstRespondCall(respond)[0]).toBe(false);
+    expect(firstRespondCall(respond)[2]?.message).toContain("authority is no longer active");
+    expect(deliveryCall()?.skipQueue).toBe(true);
+    expect(platformSend).not.toHaveBeenCalled();
+  });
+
+  it("does not send after turn capability closes while delegated authority remains active", async () => {
+    const enteredDelivery = createDeferred<null>();
+    const resumeDelivery = createDeferred<null>();
+    const platformSend = vi.fn();
+    mocks.deliverOutboundPayloads.mockImplementationOnce(
+      async (params: { onPlatformSendDispatch?: () => Promise<void> }) => {
+        enteredDelivery.resolve(null);
+        await resumeDelivery.promise;
+        await params.onPlatformSendDispatch?.();
+        platformSend();
+        return [{ channel: "slack", messageId: "must-not-send" }];
+      },
+    );
+    const sessionKey = "agent:main:slack:channel:C1";
+    const operationalRunInstance = createOperationalRunInstanceRef("run-turn-capability-race");
+    const delegatedAuthority = claimAgentRunDelegatedAuthority(operationalRunInstance);
+    const messageActionTurnCapability = mintMessageActionTurnCapability({
+      agentId: "main",
+      runId: operationalRunInstance.runId,
+      sessionKey,
+    });
+    const client = {
+      internal: {
+        agentRuntimeIdentity: {
+          kind: "agentRuntime" as const,
+          agentId: "main",
+          sessionKey,
+          operationalRunInstance,
+          delegatedAuthority: { kind: "local" as const, ...delegatedAuthority },
+          messageActionContext: {
+            ...messageActionContextFromSessionKeyForTests(sessionKey),
+            turnCapability: messageActionTurnCapability,
+          },
+        },
+      },
+    };
+    const context = {
+      ...makeContext(),
+      validateAgentRuntimeApprovalAuthority: createAgentRuntimeApprovalAuthorityValidator(),
+    } as GatewayRequestContext;
+
+    try {
+      const request = runSendWithClient(
+        {
+          channel: "slack",
+          to: "channel:C1",
+          message: "must not escape",
+          sessionKey,
+          idempotencyKey: "idem-send-turn-capability-race",
+        },
+        client,
+        context,
+      );
+      await enteredDelivery.promise;
+      expect(revokeMessageActionTurnCapability(messageActionTurnCapability)).toBe(true);
+      resumeDelivery.resolve(null);
+
+      const { respond } = await request;
+      expect(firstRespondCall(respond)[0]).toBe(false);
+      expect(firstRespondCall(respond)[2]?.message).toContain("authority is no longer active");
+      expect(platformSend).not.toHaveBeenCalled();
+    } finally {
+      revokeMessageActionTurnCapability(messageActionTurnCapability);
+      releaseAgentRunDelegatedAuthority(delegatedAuthority);
+    }
+  });
+
   it("cancels a prepared terminal receipt when authority closes before action dispatch", async () => {
     const receipt = createDeferred<"started">();
     mocks.beginRestartRecoveryTerminalDelivery.mockReturnValueOnce(receipt.promise);
diff --git a/src/gateway/server-methods/send.ts b/src/gateway/server-methods/send.ts
index 25a18e4a6b59..9bceffec0343 100644
--- a/src/gateway/server-methods/send.ts
+++ b/src/gateway/server-methods/send.ts
@@ -79,7 +79,10 @@ import { DEDUPE_MAX, DEDUPE_TTL_MS } from "../server-constants.js";
 import { resolveRequestedSessionAgentId } from "../session-request-agent.js";
 import { loadSessionEntry } from "../session-utils.js";
 import { formatForLog } from "../ws-log.js";
-import { hasActiveAgentRuntimeAuthority } from "./agent-runtime-authority.js";
+import {
+  createAgentRuntimeAuthorityGuard,
+  hasActiveAgentRuntimeAuthority,
+} from "./agent-runtime-authority.js";
 import {
   resolveGatewayInflightRequest as resolveIdempotentGatewayRequest,
   runGatewayInflightWork,
@@ -1186,6 +1189,12 @@ export const sendHandlers: GatewayRequestHandlers = {
     const requestedAccountId = normalizeOptionalString(request.accountId);
     const replyToId = normalizeOptionalString(request.replyToId);
     const threadId = normalizeOptionalString(request.threadId);
+    const agentRuntimeAuthority = createAgentRuntimeAuthorityGuard(client, context, respond);
+    const hasAgentRuntimeAuthority = client?.internal?.agentRuntimeIdentity !== undefined;
+    const commitAgentRuntimeAuthority = agentRuntimeAuthority.commitGuard;
+    const onPlatformSendDispatch = commitAgentRuntimeAuthority
+      ? async () => commitAgentRuntimeAuthority()
+      : undefined;
     await withMessageOperationRoute({
       context,
       prefix: "send",
@@ -1195,7 +1204,7 @@ export const sendHandlers: GatewayRequestHandlers = {
       bindingAccountIds: [request.accountId],
       routeAccountIds: (binding) => [requestedAccountId, binding?.reservedRoute?.accountId],
       conflictMessage: "send account selections do not match",
-      authorize: () => hasActiveAgentRuntimeAuthority(client, context),
+      authorize: agentRuntimeAuthority.hasActive,
       resolveChannel: async (requestChannel) => {
         const resolved = await resolveInternalDeliveryChannel(requestChannel, context);
         if (resolved.kind !== "ready") {
@@ -1396,6 +1405,10 @@ export const sendHandlers: GatewayRequestHandlers = {
             silent: request.silent,
             formatting: request.parseMode ? { parseMode: request.parseMode } : undefined,
             onDeliveryResult: commitOutboundSessionRoute,
+            // Runtime-bound sends cannot outlive their operational run. Keep
+            // recovery from replaying them after the live authority closes.
+            onPlatformSendDispatch,
+            skipQueue: hasAgentRuntimeAuthority,
             mirror: outboundSessionKey
               ? {
                   sessionKey: outboundSessionKey,
@@ -1428,6 +1441,9 @@ export const sendHandlers: GatewayRequestHandlers = {
             channel,
           });
         } catch (err) {
+          if (hasAgentRuntimeAuthority && !agentRuntimeAuthority.hasActive()) {
+            return createGatewayInflightAuthorityFailure({ context, dedupeKey, channel });
+          }
           return createGatewayInflightUnavailableFailure({ context, dedupeKey, channel, err });
         }
       },
diff --git a/src/infra/outbound/deliver-channel.ts b/src/infra/outbound/deliver-channel.ts
index fba7a7388c6f..5be9c95dc277 100644
--- a/src/infra/outbound/deliver-channel.ts
+++ b/src/infra/outbound/deliver-channel.ts
@@ -26,6 +26,7 @@ import type {
   DurableFinalDeliveryRequirement,
   DurableFinalDeliveryRequirements,
   OutboundDurableDeliverySupport,
+  PlatformSendRoute,
 } from "./deliver-contracts.js";
 import { PlatformMessageNotDispatchedError, type OutboundDeliveryResult } from "./deliver-types.js";
 import {
@@ -256,6 +257,16 @@ function createPluginHandler(
   const baseCtx = createChannelOutboundContextBase(params);
   const sendText = outbound?.sendText;
   const sendMedia = outbound?.sendMedia;
+  // Adapters may ignore the context callback; the core handoff must still fence
+  // closed turn authority before transport code can run.
+  const dispatchToAdapter = async <T>(
+    route: PlatformSendRoute,
+    send: () => Promise<T>,
+  ): Promise<T> => {
+    await params.onPlatformSendStart?.(route);
+    await params.onDirectAdapterHandoff?.();
+    return await send();
+  };
   // A prepared transport id identifies one atomic platform message. Splitting it
   // would either reuse the id or leave later chunks outside reply correlation.
   const chunker = baseCtx.preparedMessageId ? null : (outbound?.chunker ?? null);
@@ -417,18 +428,15 @@ function createPluginHandler(
               const sent = await runChannelMessageSendWithLifecycle({
                 lifecycle: messageLifecycle,
                 ctx: messagePayloadCtx,
-                send: async () => {
-                  await params.onPlatformSendStart?.(messagePayloadCtx);
-                  return await messagePayload(messagePayloadCtx);
-                },
+                send: () =>
+                  dispatchToAdapter(messagePayloadCtx, () => messagePayload(messagePayloadCtx)),
               });
               return attachOutboundDeliveryCommitHook(
                 normalizeChannelMessageSendResult(params.channel, sent.result),
                 sent.afterCommit,
               );
             }
-            await params.onPlatformSendStart?.(payloadCtx);
-            return outbound!.sendPayload!(payloadCtx);
+            return dispatchToAdapter(payloadCtx, () => outbound!.sendPayload!(payloadCtx));
           }
         : undefined,
     sendFormattedText: outbound?.sendFormattedText
@@ -438,8 +446,9 @@ function createPluginHandler(
             text,
           };
           assertUnknownSendReconciliationKind("text");
-          await params.onPlatformSendStart?.(formattedCtx);
-          return await outbound.sendFormattedText!(formattedCtx);
+          return await dispatchToAdapter(formattedCtx, () =>
+            outbound.sendFormattedText!(formattedCtx),
+          );
         }
       : undefined,
     sendFormattedMedia: outbound?.sendFormattedMedia
@@ -450,8 +459,9 @@ function createPluginHandler(
             mediaUrl,
           };
           assertUnknownSendReconciliationKind("media");
-          await params.onPlatformSendStart?.(formattedCtx);
-          return await outbound.sendFormattedMedia!(formattedCtx);
+          return await dispatchToAdapter(formattedCtx, () =>
+            outbound.sendFormattedMedia!(formattedCtx),
+          );
         }
       : undefined,
     sendText: async (text, overrides) => {
@@ -466,18 +476,14 @@ function createPluginHandler(
         const sent = await runChannelMessageSendWithLifecycle({
           lifecycle: messageLifecycle,
           ctx: messageTextCtx,
-          send: async () => {
-            await params.onPlatformSendStart?.(messageTextCtx);
-            return await messageText(messageTextCtx);
-          },
+          send: () => dispatchToAdapter(messageTextCtx, () => messageText(messageTextCtx)),
         });
         return attachOutboundDeliveryCommitHook(
           normalizeChannelMessageSendResult(params.channel, sent.result),
           sent.afterCommit,
         );
       }
-      await params.onPlatformSendStart?.(textCtx);
-      return sendText!(textCtx);
+      return dispatchToAdapter(textCtx, () => sendText!(textCtx));
     },
     buildTargetRef,
     sendMedia: async (caption, mediaUrl, overrides) => {
@@ -493,10 +499,7 @@ function createPluginHandler(
         const sent = await runChannelMessageSendWithLifecycle({
           lifecycle: messageLifecycle,
           ctx: messageMediaCtx,
-          send: async () => {
-            await params.onPlatformSendStart?.(messageMediaCtx);
-            return await messageMedia(messageMediaCtx);
-          },
+          send: () => dispatchToAdapter(messageMediaCtx, () => messageMedia(messageMediaCtx)),
         });
         return attachOutboundDeliveryCommitHook(
           normalizeChannelMessageSendResult(params.channel, sent.result),
@@ -504,11 +507,9 @@ function createPluginHandler(
         );
       }
       if (sendMedia) {
-        await params.onPlatformSendStart?.(mediaCtx);
-        return sendMedia(mediaCtx);
+        return dispatchToAdapter(mediaCtx, () => sendMedia(mediaCtx));
       }
-      await params.onPlatformSendStart?.(mediaCtx);
-      return sendText!(mediaCtx);
+      return dispatchToAdapter(mediaCtx, () => sendText!(mediaCtx));
     },
   };
 }
diff --git a/src/infra/outbound/deliver-contracts.ts b/src/infra/outbound/deliver-contracts.ts
index 9aa1bb333d2c..8e335e1ce05b 100644
--- a/src/infra/outbound/deliver-contracts.ts
+++ b/src/infra/outbound/deliver-contracts.ts
@@ -145,6 +145,7 @@ export type ChannelHandlerParams = {
   preparedMessageId?: string;
   requiredUnknownSendReconciliation?: boolean;
   onPlatformSendStart?: (route: PlatformSendRoute) => Promise<void>;
+  onDirectAdapterHandoff?: () => Promise<void>;
   onPlatformSendDispatch?: () => Promise<void>;
   onDeliveryResult?: (result: OutboundDeliveryResult) => Promise<void> | void;
 };
@@ -201,6 +202,8 @@ export type DeliverOutboundPayloadsCoreParams = {
   requiredUnknownSendReconciliation?: boolean;
   /** @internal Caller preflight explicitly required provider unknown-send reconciliation. */
   requireUnknownSendReconciliation?: boolean;
+  /** @internal Revalidate caller authority before direct adapter code can run. */
+  onDirectAdapterHandoff?: () => Promise<void>;
   /** @internal Refresh durable timing before recipient-visible or finalizing platform I/O. */
   onPlatformSendDispatch?: () => Promise<void>;
   /** Session/agent context used for hooks and media local-root scoping. */
diff --git a/src/infra/outbound/deliver-core.ts b/src/infra/outbound/deliver-core.ts
index 30ccc0ade1c8..fa29b0675e1d 100644
--- a/src/infra/outbound/deliver-core.ts
+++ b/src/infra/outbound/deliver-core.ts
@@ -98,6 +98,7 @@ export async function deliverOutboundPayloadsCore(
         // Carry its source index without polluting the persisted platform route.
         await params.onPlatformSendStart?.(route, activeSourceIndex);
       },
+      onDirectAdapterHandoff: params.onDirectAdapterHandoff,
       onPlatformSendDispatch: params.onPlatformSendDispatch,
       onDeliveryResult: reportIdentifiedDeliveryResult,
     });
diff --git a/src/infra/outbound/deliver-queue-execute.ts b/src/infra/outbound/deliver-queue-execute.ts
index b7ffc1bf00d2..ef650e64c343 100644
--- a/src/infra/outbound/deliver-queue-execute.ts
+++ b/src/infra/outbound/deliver-queue-execute.ts
@@ -233,6 +233,11 @@ export async function deliverOutboundPayloadsWithQueueCleanup(
       params.abortSignal?.throwIfAborted();
       platformSendStarted = true;
     },
+    onDirectAdapterHandoff: async () => {
+      params.abortSignal?.throwIfAborted();
+      await params.onPlatformSendDispatch?.();
+      params.abortSignal?.throwIfAborted();
+    },
     onPlatformSendDispatch: async () => {
       params.abortSignal?.throwIfAborted();
       // Once any payload returns an identity, unknown-after-send protects the whole batch.
diff --git a/src/infra/outbound/deliver.test.ts b/src/infra/outbound/deliver.test.ts
index 16e44a35e528..374baee69921 100644
--- a/src/infra/outbound/deliver.test.ts
+++ b/src/infra/outbound/deliver.test.ts
@@ -22,6 +22,7 @@ import { addTestHook } from "../../plugins/hooks.test-fixtures.js";
 import { createEmptyPluginRegistry } from "../../plugins/registry.js";
 import { setActivePluginRegistry } from "../../plugins/runtime.js";
 import type { PluginHookRegistration } from "../../plugins/types.js";
+import { createDeferredCore } from "../../shared/deferred.js";
 import { createOutboundTestPlugin, createTestRegistry } from "../../test-utils/channel-plugins.js";
 import { createInternalHookEventPayload } from "../../test-utils/internal-hook-event-payload.js";
 import { createOpenClawTestState } from "../../test-utils/openclaw-test-state.js";
@@ -906,6 +907,7 @@ describe("deliverOutboundPayloads", () => {
       undefined,
       expect.objectContaining({ replyToId: undefined, threadId: undefined }),
     );
+    expect(queueMocks.markDeliveryPlatformSendDispatched).toHaveBeenCalledOnce();
     const [successParams] = expectDefined(
       (
         afterSendSuccess.mock.calls as unknown as Array<
@@ -932,6 +934,40 @@ describe("deliverOutboundPayloads", () => {
     expect(results[0]?.messageId).toBe("message-adapter-1");
   });
 
+  it("revalidates before direct adapter handoff when the adapter ignores the dispatch callback", async () => {
+    const enteredPreflight = createDeferredCore();
+    const resumePreflight = createDeferredCore();
+    const messageSendText = vi.fn(async () => ({
+      messageId: "must-not-send",
+      receipt: createMessageReceiptFromOutboundResults({
+        results: [{ channel: "matrix", messageId: "must-not-send" }],
+        kind: "text",
+      }),
+    }));
+    setMatrixMessageAdapter({
+      id: "matrix",
+      send: {
+        lifecycle: {
+          beforeSendAttempt: async () => {
+            enteredPreflight.resolve();
+            await resumePreflight.promise;
+          },
+        },
+        text: messageSendText,
+      },
+    });
+    const onPlatformSendDispatch = vi.fn(async () => {
+      throw new Error("turn authority closed");
+    });
+
+    const delivery = deliverMatrix({ skipQueue: true, onPlatformSendDispatch });
+    await enteredPreflight.promise;
+    resumePreflight.resolve();
+
+    await expect(delivery).rejects.toThrow("turn authority closed");
+    expect(messageSendText).not.toHaveBeenCalled();
+  });
+
   it("does not claim platform custody when message adapter preflight fails", async () => {
     const messageSendText = vi.fn();
     setMatrixMessageAdapter({
diff --git a/src/infra/outbound/message-action-contracts.ts b/src/infra/outbound/message-action-contracts.ts
index eb7ed97c9f0d..0687c6e5169d 100644
--- a/src/infra/outbound/message-action-contracts.ts
+++ b/src/infra/outbound/message-action-contracts.ts
@@ -68,6 +68,8 @@ export type MessageActionInput = {
   /** @internal Exact admitted execution provenance for owner-native delivery audit. */
   executionIdentityToken?: ExecutionIdentityAdmissionToken;
   toolContext?: ChannelThreadingToolContext;
+  /** @internal Host media grant captured before untrusted caller code can mutate config. */
+  mediaAccess?: OutboundMediaAccess;
   gateway?: MessageActionGateway;
   deps?: OutboundSendDeps;
   sessionKey?: string;
@@ -94,6 +96,10 @@ export type MessageActionInput = {
   onDeliveryIntent?: (intent: DurableMessageSendIntent) => void;
   /** @internal Runs on identified platform evidence before queue acknowledgement. */
   onDeliveryResult?: (result: OutboundDeliveryResult) => Promise<void> | void;
+  /** @internal Revalidates caller authority immediately before recipient-visible I/O. */
+  onPlatformSendDispatch?: () => Promise<void>;
+  /** @internal Keep ephemeral-authority sends out of replayable recovery. */
+  skipQueue?: boolean;
   /** @internal Runs when broadcast converts a typed target denial into result text. */
   onActionDenied?: (
     error: MessageActionDeniedError,
diff --git a/src/infra/outbound/message-action-runner.ts b/src/infra/outbound/message-action-runner.ts
index f5f7190424dc..8d96199dd442 100644
--- a/src/infra/outbound/message-action-runner.ts
+++ b/src/infra/outbound/message-action-runner.ts
@@ -386,20 +386,22 @@ export async function runMessageAction(input: MessageActionInput): Promise<Messa
     structuredAttachments: structuredAttachmentMode,
   });
 
-  const mediaAccess = resolveAgentScopedOutboundMediaAccess({
-    cfg,
-    agentId: resolvedAgentId,
-    mediaSources: collectActionMediaSourceHints(params, extraActionMediaSourceParamKeys, {
-      structuredAttachments: structuredAttachmentMode,
-    }),
-    sessionKey: input.sessionKey,
-    messageProvider: input.sessionKey ? undefined : channel,
-    accountId: input.sessionKey ? (input.requesterAccountId ?? accountId) : accountId,
-    requesterSenderId: input.requesterSenderId,
-    requesterSenderName: input.requesterSenderName,
-    requesterSenderUsername: input.requesterSenderUsername,
-    requesterSenderE164: input.requesterSenderE164,
-  });
+  const mediaAccess =
+    input.mediaAccess ??
+    resolveAgentScopedOutboundMediaAccess({
+      cfg,
+      agentId: resolvedAgentId,
+      mediaSources: collectActionMediaSourceHints(params, extraActionMediaSourceParamKeys, {
+        structuredAttachments: structuredAttachmentMode,
+      }),
+      sessionKey: input.sessionKey,
+      messageProvider: input.sessionKey ? undefined : channel,
+      accountId: input.sessionKey ? (input.requesterAccountId ?? accountId) : accountId,
+      requesterSenderId: input.requesterSenderId,
+      requesterSenderName: input.requesterSenderName,
+      requesterSenderUsername: input.requesterSenderUsername,
+      requesterSenderE164: input.requesterSenderE164,
+    });
   const mediaPolicy = resolveAttachmentMediaPolicy({
     sandboxRoot: input.sandboxRoot,
     mediaAccess,
diff --git a/src/infra/outbound/message-action-send.ts b/src/infra/outbound/message-action-send.ts
index a52d11c325c5..5579b75e92c1 100644
--- a/src/infra/outbound/message-action-send.ts
+++ b/src/infra/outbound/message-action-send.ts
@@ -483,20 +483,22 @@ export async function executeMessageSend(ctx: ResolvedActionContext): Promise<Me
   delete params.voiceProvider;
   delete params.voiceId;
   throwIfAborted(abortSignal);
-  const mediaAccess = resolveAgentScopedOutboundMediaAccess({
-    cfg,
-    agentId,
-    mediaSources: collectActionMediaSourceHints(params, ctx.extraActionMediaSourceParamKeys, {
-      structuredAttachments: "all",
-    }),
-    sessionKey: input.sessionKey,
-    messageProvider: input.sessionKey ? undefined : channel,
-    accountId: input.sessionKey ? (input.requesterAccountId ?? accountId) : accountId,
-    requesterSenderId: input.requesterSenderId,
-    requesterSenderName: input.requesterSenderName,
-    requesterSenderUsername: input.requesterSenderUsername,
-    requesterSenderE164: input.requesterSenderE164,
-  });
+  const mediaAccess =
+    input.mediaAccess ??
+    resolveAgentScopedOutboundMediaAccess({
+      cfg,
+      agentId,
+      mediaSources: collectActionMediaSourceHints(params, ctx.extraActionMediaSourceParamKeys, {
+        structuredAttachments: "all",
+      }),
+      sessionKey: input.sessionKey,
+      messageProvider: input.sessionKey ? undefined : channel,
+      accountId: input.sessionKey ? (input.requesterAccountId ?? accountId) : accountId,
+      requesterSenderId: input.requesterSenderId,
+      requesterSenderName: input.requesterSenderName,
+      requesterSenderUsername: input.requesterSenderUsername,
+      requesterSenderE164: input.requesterSenderE164,
+    });
 
   // Required queue persistence is itself an ownership decision: neither the
   // remote gateway action nor a provider-native action may bypass core queueing.
@@ -597,6 +599,8 @@ export async function executeMessageSend(ctx: ResolvedActionContext): Promise<Me
       deliveryIntentId: input.deliveryIntentId,
       deliveryCompletion: input.deliveryCompletion,
       onDeliveryIntent: input.onDeliveryIntent,
+      onPlatformSendDispatch: input.onPlatformSendDispatch,
+      skipQueue: input.skipQueue,
       // Identified platform evidence is the first success proof on the core
       // path; commit the route here so the transcript mirror (which runs later
       // in the same delivery) can resolve a just-created session entry.
diff --git a/src/infra/outbound/message-gateway-options.ts b/src/infra/outbound/message-gateway-options.ts
index c890c52cbe43..564417b29b1b 100644
--- a/src/infra/outbound/message-gateway-options.ts
+++ b/src/infra/outbound/message-gateway-options.ts
@@ -16,6 +16,7 @@ export type OutboundMessageGatewayOptionsInput = {
   clientName?: GatewayClientName;
   clientDisplayName?: string;
   mode?: GatewayClientMode;
+  resolveAgentRuntimeIdentityToken?: () => Promise<string | undefined>;
 };
 
 /** Normalizes outbound gateway options and fills CLI defaults. */
diff --git a/src/infra/outbound/message.channels.test.ts b/src/infra/outbound/message.channels.test.ts
index ca9809d8343f..2f5b806b6e68 100644
--- a/src/infra/outbound/message.channels.test.ts
+++ b/src/infra/outbound/message.channels.test.ts
@@ -1,13 +1,17 @@
 // Covers channel-specific outbound adapter behavior for message sends,
 // structured payloads, and channel capability interactions.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { useAutoCleanupTempDirTracker } from "../../../test/helpers/temp-dir.js";
 import type { ChannelOutboundAdapter, ChannelPlugin } from "../../channels/plugins/types.public.js";
+import { pinRuntimePaths } from "../../config/paths.js";
 import { setActivePluginRegistry } from "../../plugins/runtime.js";
 import {
   createChannelTestPluginBase,
   createTestRegistry,
 } from "../../test-utils/channel-plugins.js";
+import { withEnvAsync } from "../../test-utils/env.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../../utils/message-channel.js";
+import { drainPendingDeliveriesCore } from "./delivery-queue-recovery.js";
 
 const setRegistry = (registry: ReturnType<typeof createTestRegistry>) => {
   setActivePluginRegistry(registry);
@@ -22,6 +26,7 @@ vi.mock("../../gateway/call.js", () => ({
 
 let sendMessage: typeof import("./message.js").sendMessage;
 let sendPoll: typeof import("./message.js").sendPoll;
+const tempDirs = useAutoCleanupTempDirTracker(afterEach);
 
 beforeAll(async () => {
   ({ sendMessage, sendPoll } = await import("./message.js"));
@@ -58,6 +63,61 @@ function gatewayCall(): {
   };
 }
 
+describe("sendMessage live-only delivery", () => {
+  it("keeps ephemeral-authority sends out of recovery after revocation", async () => {
+    const stateDir = tempDirs.make("openclaw-live-only-delivery-");
+    try {
+      await withEnvAsync({ OPENCLAW_STATE_DIR: stateDir }, async () => {
+        pinRuntimePaths();
+        let authorityActive = true;
+        const sendText = vi.fn(async (ctx: { onPlatformSendDispatch?: () => Promise<void> }) => {
+          await ctx.onPlatformSendDispatch?.();
+          return { channel: "threadchat", messageId: "live-only-1" };
+        });
+        const plugin: ChannelPlugin = {
+          ...createChannelTestPluginBase({ id: "threadchat" }),
+          outbound: { deliveryMode: "direct", sendText },
+        };
+        setRegistry(createTestRegistry([{ pluginId: "threadchat", source: "test", plugin }]));
+        const onDeliveryIntent = vi.fn(() => {
+          throw new Error("simulated crash after queue persistence");
+        });
+
+        await sendMessage({
+          cfg: {},
+          to: "channel:town-square",
+          content: "live only",
+          channel: "threadchat",
+          skipQueue: true,
+          onDeliveryIntent,
+          onPlatformSendDispatch: async () => {
+            if (!authorityActive) {
+              throw new Error("delivery authority revoked");
+            }
+          },
+        });
+        expect(onDeliveryIntent).not.toHaveBeenCalled();
+        expect(sendText).toHaveBeenCalledOnce();
+
+        authorityActive = false;
+        const recoveredDelivery = vi.fn(async () => []);
+        await drainPendingDeliveriesCore({
+          drainKey: `live-only-${stateDir}`,
+          logLabel: "Live-only delivery test",
+          cfg: {},
+          stateDir,
+          deliver: recoveredDelivery,
+          log: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+          selectEntry: () => ({ match: true, bypassBackoff: true }),
+        });
+        expect(recoveredDelivery).not.toHaveBeenCalled();
+      });
+    } finally {
+      pinRuntimePaths();
+    }
+  });
+});
+
 describe("sendMessage channel normalization", () => {
   it("threads resolved cfg through alias + target normalization in outbound dispatch", async () => {
     const resolvedCfg = {
@@ -482,6 +542,61 @@ describe("gateway url override hardening", () => {
     });
   });
 
+  it("rejects revoked authority before a gateway send RPC", async () => {
+    setThreadChatGatewayRegistry();
+    const onPlatformSendDispatch = vi.fn(async () => {
+      throw new Error("delivery authority revoked");
+    });
+
+    await expect(
+      sendMessage({
+        cfg: {},
+        to: "channel:town-square",
+        content: "hi",
+        channel: "threadchat",
+        onPlatformSendDispatch,
+      }),
+    ).rejects.toThrow("delivery authority revoked");
+
+    expect(onPlatformSendDispatch).toHaveBeenCalledOnce();
+    expect(callGatewayMock).not.toHaveBeenCalled();
+  });
+
+  it("carries live authority across a gateway send RPC", async () => {
+    setThreadChatGatewayRegistry();
+    let authorityActive = true;
+    const queueDelivery = vi.fn();
+    const platformSend = vi.fn();
+    callGatewayMock.mockImplementationOnce(async (call: { agentRuntimeIdentityToken?: string }) => {
+      if (call.agentRuntimeIdentityToken && !authorityActive) {
+        throw new Error("agent runtime authority is no longer active");
+      }
+      queueDelivery();
+      platformSend();
+      return { messageId: "must-not-send" };
+    });
+
+    await expect(
+      sendMessage({
+        cfg: {},
+        to: "channel:town-square",
+        content: "must not escape",
+        channel: "threadchat",
+        gateway: {
+          clientName: GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT,
+          mode: GATEWAY_CLIENT_MODES.BACKEND,
+          resolveAgentRuntimeIdentityToken: async () => "runtime-identity",
+        },
+        onPlatformSendDispatch: async () => {
+          authorityActive = false;
+        },
+      }),
+    ).rejects.toThrow("agent runtime authority is no longer active");
+
+    expect(queueDelivery).not.toHaveBeenCalled();
+    expect(platformSend).not.toHaveBeenCalled();
+  });
+
   it("drops unused buffer metadata when explicit gateway media is present", async () => {
     const result = await sendThreadChatGatewayMessage({
       mediaUrl: "https://example.com/photo.png",
diff --git a/src/infra/outbound/message.ts b/src/infra/outbound/message.ts
index 407f2fff6cfe..ffccd49002ab 100644
--- a/src/infra/outbound/message.ts
+++ b/src/infra/outbound/message.ts
@@ -122,6 +122,10 @@ type MessageSendParams = {
   onDeliveryIntent?: (intent: DurableMessageSendIntent) => void;
   /** @internal Runs on identified platform evidence before queue acknowledgement. */
   onDeliveryResult?: (result: OutboundDeliveryResult) => Promise<void> | void;
+  /** @internal Revalidates caller authority immediately before recipient-visible I/O. */
+  onPlatformSendDispatch?: () => Promise<void>;
+  /** @internal Keep ephemeral-authority sends out of replayable recovery. */
+  skipQueue?: boolean;
   mirror?: OutboundMirror;
   /** @internal Reports the effective payload only after an identified direct send. */
   onDeliveredPayload?: (payload: NormalizedOutboundPayload) => void;
@@ -300,9 +304,14 @@ async function callMessageGateway<T>(params: {
   gateway?: OutboundMessageGatewayOptionsInput;
   method: string;
   params: Record<string, unknown>;
+  onPlatformSendDispatch?: () => Promise<void>;
 }): Promise<T> {
   const { callGatewayLeastPrivilege } = await loadMessageGatewayRuntime();
   const gateway = resolveGatewayOptions(params.gateway);
+  // Mint before the local dispatch fence so revocation during RPC is enforced
+  // by the Gateway's live operational-run validator, not token freshness.
+  const agentRuntimeIdentityToken = await params.gateway?.resolveAgentRuntimeIdentityToken?.();
+  await params.onPlatformSendDispatch?.();
   return await callGatewayLeastPrivilege<T>({
     url: gateway.url,
     token: gateway.token,
@@ -312,6 +321,7 @@ async function callMessageGateway<T>(params: {
     clientName: gateway.clientName,
     clientDisplayName: gateway.clientDisplayName,
     mode: gateway.mode,
+    agentRuntimeIdentityToken,
   });
 }
 
@@ -446,6 +456,10 @@ export async function sendMessage(params: MessageSendParams): Promise<MessageSen
       completionRetention: params.completionRetention,
       ...(params.onDeliveryIntent ? { onDeliveryIntent: params.onDeliveryIntent } : {}),
       ...(params.onDeliveryResult ? { onDeliveryResult: params.onDeliveryResult } : {}),
+      ...(params.onPlatformSendDispatch
+        ? { onPlatformSendDispatch: params.onPlatformSendDispatch }
+        : {}),
+      skipQueue: params.skipQueue,
       ...(params.onDeliveredPayload ? { onDeliveredPayload: params.onDeliveredPayload } : {}),
       mirror: params.mirror
         ? {
@@ -482,6 +496,7 @@ export async function sendMessage(params: MessageSendParams): Promise<MessageSen
   const result = await callMessageGateway<{ messageId: string }>({
     gateway: params.gateway,
     method: "send",
+    onPlatformSendDispatch: params.onPlatformSendDispatch,
     params: {
       to: params.to,
       message: params.content,
diff --git a/src/infra/outbound/outbound-send-service.ts b/src/infra/outbound/outbound-send-service.ts
index 1e744c9ba0a7..b6ba17c918ed 100644
--- a/src/infra/outbound/outbound-send-service.ts
+++ b/src/infra/outbound/outbound-send-service.ts
@@ -26,12 +26,12 @@ import { createSubsystemLogger } from "../../logging/subsystem.js";
 import type { OutboundMediaAccess, OutboundMediaReadFile } from "../../media/load-options.js";
 import { resolveAgentScopedOutboundMediaAccess } from "../../media/read-capability.js";
 import { extractToolPayload } from "../../plugin-sdk/tool-payload.js";
-import type { GatewayClientMode, GatewayClientName } from "../../utils/message-channel.js";
 import { formatErrorMessage } from "../errors.js";
 import { throwIfAborted } from "./abort.js";
 import type { OutboundDeliveryResult } from "./deliver-types.js";
 import type { NormalizedOutboundPayload, OutboundSendDeps } from "./deliver.js";
 import type { DurableDeliveryCompletion } from "./delivery-completion.js";
+import type { MessageActionGateway } from "./message-action-contracts.js";
 import { collectActionMediaSourceHints } from "./message-action-params.js";
 import type { MessagePollResult, MessageSendResult } from "./message.js";
 import { sendMessage, sendPoll } from "./message.js";
@@ -39,16 +39,6 @@ import type { OutboundMirror } from "./mirror.js";
 
 const log = createSubsystemLogger("outbound/send-service");
 
-/** Gateway connection settings forwarded to outbound send helpers. */
-type OutboundGatewayContext = {
-  url?: string;
-  token?: string;
-  timeoutMs?: number;
-  clientName: GatewayClientName;
-  clientDisplayName?: string;
-  mode: GatewayClientMode;
-};
-
 /** Shared execution context for message-tool send and poll actions. */
 type OutboundSendContext = {
   cfg: OpenClawConfig;
@@ -75,7 +65,7 @@ type OutboundSendContext = {
   runId?: string;
   executionIdentityToken?: ExecutionIdentityAdmissionToken;
   inboundEventKind?: InboundEventKind;
-  gateway?: OutboundGatewayContext;
+  gateway?: MessageActionGateway;
   toolContext?: ChannelThreadingToolContext;
   deps?: OutboundSendDeps;
   dryRun: boolean;
@@ -98,6 +88,10 @@ type OutboundSendContext = {
   onDeliveryIntent?: (intent: DurableMessageSendIntent) => void;
   /** Runs on identified platform evidence before queue acknowledgement. */
   onDeliveryResult?: (result: OutboundDeliveryResult) => Promise<void> | void;
+  /** Revalidates caller authority immediately before recipient-visible I/O. */
+  onPlatformSendDispatch?: () => Promise<void>;
+  /** Keep ephemeral-authority sends out of replayable recovery. */
+  skipQueue?: boolean;
   /** Runs once a plugin action accepted the send, before transcript mirroring. */
   onPluginSendAccepted?: () => Promise<void>;
 };
@@ -195,6 +189,8 @@ async function sendCoreMessage(params: {
     requireUnknownSendReconciliation: params.ctx.requireQueuePersistence ? false : undefined,
     onDeliveryIntent: params.ctx.onDeliveryIntent,
     onDeliveryResult: params.ctx.onDeliveryResult,
+    onPlatformSendDispatch: params.ctx.onPlatformSendDispatch,
+    skipQueue: params.ctx.skipQueue,
     onDeliveredPayload: (payload) => deliveredPayloads.push(payload),
   });
   const deliveredText =
diff --git a/src/plugins/tool-descriptor-cache.test.ts b/src/plugins/tool-descriptor-cache.test.ts
index 01906276fc3f..1742988ccd61 100644
--- a/src/plugins/tool-descriptor-cache.test.ts
+++ b/src/plugins/tool-descriptor-cache.test.ts
@@ -249,6 +249,26 @@ describe("plugin tool descriptor cache keys", () => {
     expect(firstKey).not.toBe(secondKey);
   });
 
+  it("varies descriptor keys by delivery availability", () => {
+    const base = {
+      pluginId: "demo",
+      source: "/tmp/demo.js",
+      contractToolNames: ["delivery_tool"],
+      ctx: { workspaceDir: "/tmp/workspace" },
+    };
+
+    const withoutDelivery = buildPluginToolDescriptorCacheKey(base);
+    const withDelivery = buildPluginToolDescriptorCacheKey({
+      ...base,
+      ctx: {
+        ...base.ctx,
+        delivery: { send: vi.fn() },
+      },
+    });
+
+    expect(withDelivery).not.toBe(withoutDelivery);
+  });
+
   it("varies descriptor keys by trusted owner state", () => {
     const base = {
       pluginId: "demo",
diff --git a/src/plugins/tool-descriptor-cache.ts b/src/plugins/tool-descriptor-cache.ts
index 5042c670e610..7003b25891b7 100644
--- a/src/plugins/tool-descriptor-cache.ts
+++ b/src/plugins/tool-descriptor-cache.ts
@@ -114,6 +114,7 @@ function buildDescriptorContextCacheKey(params: {
     agentAccountId: ctx.agentAccountId ?? null,
     nativeChannelId: ctx.nativeChannelId ?? null,
     deliveryContext: ctx.deliveryContext ?? null,
+    deliveryAvailable: ctx.delivery !== undefined,
     requesterSenderId: ctx.requesterSenderId ?? null,
     senderIsOwner: ctx.senderIsOwner ?? null,
     sandboxed: ctx.sandboxed ?? null,
diff --git a/src/plugins/tool-types.ts b/src/plugins/tool-types.ts
index 245ae579734f..c68dda253fd3 100644
--- a/src/plugins/tool-types.ts
+++ b/src/plugins/tool-types.ts
@@ -13,6 +13,11 @@ export type OpenClawPluginActiveModelContext = {
   modelRef?: string;
 };
 
+/** Current-turn outbound delivery capability bound to the host-selected route and media policy. */
+export type OpenClawPluginToolDelivery = {
+  send: (params: { text?: string; mediaUrl?: string }) => Promise<void>;
+};
+
 /** Trusted execution context passed to plugin-owned agent tool factories. */
 export type OpenClawPluginToolContext = {
   config?: OpenClawConfig;
@@ -52,6 +57,8 @@ export type OpenClawPluginToolContext = {
   resolveApiKeyForProvider?: (providerId: string) => Promise<string | undefined>;
   /** Trusted ambient delivery route for the active agent/session. */
   deliveryContext?: DeliveryContext;
+  /** Host-bound current-route delivery. Retained copies fail after the owning turn closes. */
+  delivery?: OpenClawPluginToolDelivery;
   /** Trusted platform-native conversation id for the active inbound turn. */
   nativeChannelId?: string;
   /** Trusted sender id from inbound context (runtime-provided, not tool args). */

From 81ace374f99f9d9adf277dfd0f4218c57222cbe5 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 10:47:10 -0700
Subject: [PATCH 046/124] fix(auth): stop advising a retry when the auth store
 needs migration (#127306)

Writing an auth profile on an install whose credentials still live in the
retired JSON store printed two contradictory lines: the real migration error,
followed by a generic "the auth store lock may be busy. Wait a moment and
retry." An operator reading the last line retries forever, because nothing is
locked and the write can never succeed until Doctor migrates the store.

updateAuthProfileStoreWithLock wrapped its transaction in a blanket catch that
logged a warn and returned null, erasing the failure's identity. Callers only
saw null, so the sole guess available to them was lock contention. Read paths
already let AuthProfileMigrationRequiredError and AuthProfileStoreUnreadableError
through; only the write path swallowed them.

Rethrow those two credential-boundary errors at the producer and keep null for
genuine write failures, which is what the lock hint was always describing. All
three sibling call sites (upsertAuthProfileWithLockOrThrow, models auth logout,
models auth order set) funnel through that null, so they are fixed by the one
change. Onboard now prints only the migration line, and `openclaw doctor --fix`
followed by the same onboard command succeeds.
---
 src/agents/auth-profiles/source-check.test.ts |  6 +++-
 src/agents/auth-profiles/store.ts             | 10 +++++-
 .../upsert-with-lock.sqlite.test.ts           | 31 ++++++++++++++++++-
 3 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/src/agents/auth-profiles/source-check.test.ts b/src/agents/auth-profiles/source-check.test.ts
index 694419b3d336..d4aedc016c5f 100644
--- a/src/agents/auth-profiles/source-check.test.ts
+++ b/src/agents/auth-profiles/source-check.test.ts
@@ -79,7 +79,11 @@ describe("hasAuthProfileStoreSourceForProvider", () => {
     writePersistedAuthProfileStoreRaw(unreadableStore, agentDir);
     const updater = vi.fn(() => true);
 
-    await expect(updateAuthProfileStoreWithLock({ agentDir, updater })).resolves.toBeNull();
+    // The unreadable store names its own remediation; a null return would make
+    // callers report generic lock contention instead.
+    await expect(updateAuthProfileStoreWithLock({ agentDir, updater })).rejects.toThrow(
+      "is unreadable; run openclaw doctor --fix",
+    );
     expect(updater).not.toHaveBeenCalled();
     expect(readPersistedAuthProfileStoreRaw(agentDir)).toEqual(unreadableStore);
   });
diff --git a/src/agents/auth-profiles/store.ts b/src/agents/auth-profiles/store.ts
index 7e5b78ba46e0..8227bbdcc2f4 100644
--- a/src/agents/auth-profiles/store.ts
+++ b/src/agents/auth-profiles/store.ts
@@ -862,7 +862,7 @@ function mergeRuntimeExternalProfileState(params: {
   return merged;
 }
 
-/** Apply an auth store update inside the SQLite write lock. */
+/** Apply an auth store update inside the SQLite write lock; null on write failure, rethrows credential-boundary errors. */
 export async function updateAuthProfileStoreWithLock(params: {
   agentDir?: string;
   sharedStoreWrite?: boolean;
@@ -896,6 +896,14 @@ export async function updateAuthProfileStoreWithLock(params: {
       { sharedStoreWrite: params.sharedStoreWrite, stateDir: params.stateDir },
     );
   } catch (error) {
+    // Credential-boundary failures name their own remediation; collapsing them
+    // into `null` makes callers report a lock-contention retry that never clears.
+    const isCredentialBoundaryFailure =
+      error instanceof AuthProfileMigrationRequiredError ||
+      error instanceof AuthProfileStoreUnreadableError;
+    if (isCredentialBoundaryFailure) {
+      throw error;
+    }
     const message = error instanceof Error ? error.message : String(error);
     authProfilesLog.warn(`auth profile store update failed: ${message}`, {
       agentDir,
diff --git a/src/agents/auth-profiles/upsert-with-lock.sqlite.test.ts b/src/agents/auth-profiles/upsert-with-lock.sqlite.test.ts
index 782aead0e97d..8ac51532a8d2 100644
--- a/src/agents/auth-profiles/upsert-with-lock.sqlite.test.ts
+++ b/src/agents/auth-profiles/upsert-with-lock.sqlite.test.ts
@@ -8,6 +8,7 @@ import {
 } from "../../state/openclaw-agent-db.js";
 import { closeOpenClawStateDatabaseForTest } from "../../state/openclaw-state-db.js";
 import { withEnvAsync } from "../../test-utils/env.js";
+import { clearAuthProfileMigrationDiagnostics } from "./legacy-source-diagnostic.js";
 import { loadPersistedAuthProfileStore } from "./persisted.js";
 import {
   inspectPersistedAuthProfileStateRaw,
@@ -16,10 +17,14 @@ import {
 } from "./sqlite.js";
 import { saveAuthProfileStore, updateAuthProfileStoreWithLock } from "./store.js";
 import type { ApiKeyCredential } from "./types.js";
-import { persistAuthProfileBatch } from "./upsert-with-lock.js";
+import { persistAuthProfileBatch, upsertAuthProfileWithLockOrThrow } from "./upsert-with-lock.js";
 
 const tempDirs = useAutoCleanupTempDirTracker(afterEach);
 
+afterEach(() => {
+  clearAuthProfileMigrationDiagnostics();
+});
+
 function apiKey(key: string): ApiKeyCredential {
   return { type: "api_key", provider: "openai", key };
 }
@@ -165,6 +170,30 @@ describe("auth profile batch persistence", () => {
     });
   });
 
+  it("reports the migration remediation instead of lock-contention retry advice", async () => {
+    await withAgentDir(async (agentDir) => {
+      // Credentials still living in the retired JSON store: the write can never
+      // succeed, so retry advice would loop the operator forever.
+      fs.writeFileSync(
+        path.join(agentDir, "auth-profiles.json"),
+        JSON.stringify({
+          version: 1,
+          profiles: { "openai:legacy": apiKey("sk-json-era") },
+        }),
+      );
+
+      const failure = await upsertAuthProfileWithLockOrThrow({
+        agentDir,
+        profileId: "openai:new",
+        credential: apiKey("sk-new"),
+      }).catch((error: unknown) => error);
+
+      expect(String(failure)).toContain("requires legacy credential migration");
+      expect(String(failure)).toContain("openclaw doctor --fix");
+      expect(String(failure)).not.toContain("lock may be busy");
+    });
+  });
+
   it("leaves no partial profile batch when the SQLite state write fails", async () => {
     await withAgentDir(async (agentDir) => {
       const database = openOpenClawAgentDatabase({

From 264cc994052994fcf8145ff979778c858d9faab5 Mon Sep 17 00:00:00 2001
From: pash-openai <pash@openai.com>
Date: Fri, 21 Aug 2026 10:55:02 -0700
Subject: [PATCH 047/124] fix(codex): run newly available models through native
 account auth (#127322)

---
 extensions/codex/harness.test.ts | 45 ++++++++++++++++++++++++++++++++
 extensions/codex/harness.ts      | 15 ++++++++++-
 2 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/extensions/codex/harness.test.ts b/extensions/codex/harness.test.ts
index 2dbb0737886d..c387732d9ebf 100644
--- a/extensions/codex/harness.test.ts
+++ b/extensions/codex/harness.test.ts
@@ -248,6 +248,51 @@ describe("Codex agent harness supports()", () => {
     expect(!result.supported ? result.reason : undefined).toContain("not declared");
   });
 
+  it("lets explicitly selected Codex discover unlisted models with its own account", () => {
+    expect(
+      harness.supports({
+        provider: "openai",
+        modelId: "gpt-future",
+        requestedRuntime: "codex",
+        modelProvider: {
+          requestTransportOverrides: "none",
+          preparedAuth: { source: "harness" },
+        },
+      }),
+    ).toEqual({ supported: true, priority: 100 });
+  });
+
+  it.each([
+    {
+      label: "automatic runtime selection",
+      requestedRuntime: "auto" as const,
+      modelProvider: { preparedAuth: { source: "harness" as const } },
+    },
+    {
+      label: "an authored endpoint",
+      requestedRuntime: "codex" as const,
+      modelProvider: {
+        baseUrl: "https://relay.example.test/v1",
+        preparedAuth: { source: "harness" as const },
+      },
+    },
+    {
+      label: "an owner-selected credential",
+      requestedRuntime: "codex" as const,
+      modelProvider: { preparedAuth: { source: "profile" as const, mode: "api-key" } },
+    },
+  ])("does not infer native model access for $label", ({ requestedRuntime, modelProvider }) => {
+    const result = harness.supports({
+      provider: "openai",
+      modelId: "gpt-future",
+      requestedRuntime,
+      modelProvider: { requestTransportOverrides: "none", ...modelProvider },
+    });
+
+    expect(result.supported).toBe(false);
+    expect(!result.supported ? result.reason : undefined).toContain("not declared");
+  });
+
   it.each([
     {
       label: "forwarded OAuth subscription",
diff --git a/extensions/codex/harness.ts b/extensions/codex/harness.ts
index b1ccb94fe5bc..8fdb1698da98 100644
--- a/extensions/codex/harness.ts
+++ b/extensions/codex/harness.ts
@@ -204,6 +204,19 @@ export function createCodexAppServerAgentHarness(
       }
       const preparedAuth = ctx.modelProvider?.preparedAuth;
       const runtimePolicy = ctx.modelProvider?.runtimePolicy;
+      // Codex owns discovery and auth for new first-party models. Only trust that
+      // native account when no authored transport or host credential is involved.
+      const nativeAccountOwnsUnobservedModel =
+        provider === "openai" &&
+        ctx.requestedRuntime === "codex" &&
+        Boolean(ctx.modelId?.trim()) &&
+        preparedAuth?.source === "harness" &&
+        preparedAuth.mode === undefined &&
+        preparedAuth.requirement === undefined &&
+        ctx.modelProvider?.api === undefined &&
+        ctx.modelProvider?.baseUrl === undefined &&
+        ctx.modelProvider?.azureApiVersion === undefined &&
+        ctx.modelProvider?.request === undefined;
       if (runtimePolicy) {
         const compatible = runtimePolicy.compatibleIds.some(
           (id) => id.trim().toLowerCase() === normalizedHarnessRuntimeId,
@@ -214,7 +227,7 @@ export function createCodexAppServerAgentHarness(
             reason: "Codex cannot reproduce the prepared provider route",
           };
         }
-      } else if (ctx.modelProvider && provider !== "codex") {
+      } else if (ctx.modelProvider && provider !== "codex" && !nativeAccountOwnsUnobservedModel) {
         return {
           supported: false,
           reason: "provider route compatibility with Codex is not declared",

From 8a7bb5d1473d5decb0292698d6985754fe461475 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 10:57:56 -0700
Subject: [PATCH 048/124] perf(plugins): reuse lifecycle metadata on secrets
 hot paths (#126629)

---
 src/config/plugin-auto-enable.shared.ts       |   1 +
 src/gateway/server-reload-handlers.test.ts    |  22 +++-
 .../bundled-manifest-contract-plugins.ts      |  11 +-
 .../manifest-contract-eligibility.test.ts     |   6 +-
 src/plugins/manifest-contract-eligibility.ts  |   6 +-
 ...try-contributions.current-snapshot.test.ts |  78 ++++++++++++-
 src/plugins/plugin-registry-contributions.ts  |  59 +++++++---
 src/plugins/web-fetch-providers.runtime.ts    |   4 +
 src/plugins/web-fetch-providers.shared.ts     |   4 +
 src/plugins/web-provider-public-artifacts.ts  |  15 ++-
 src/plugins/web-provider-resolution-shared.ts |  43 +++++--
 .../web-provider-runtime-shared.test.ts       |  18 ++-
 src/plugins/web-provider-runtime-shared.ts    |  41 ++++++-
 src/plugins/web-search-providers.runtime.ts   |   4 +
 src/plugins/web-search-providers.shared.ts    |   4 +
 .../runtime-config-collectors-plugins.ts      |  10 +-
 src/secrets/runtime-web-tools.shared.ts       |   2 +
 src/secrets/runtime-web-tools.ts              |  13 +++
 src/secrets/runtime.fast-path.test.ts         | 106 +++++++++++++++---
 19 files changed, 378 insertions(+), 69 deletions(-)

diff --git a/src/config/plugin-auto-enable.shared.ts b/src/config/plugin-auto-enable.shared.ts
index dfd712ab4f14..dc00d160b06c 100644
--- a/src/config/plugin-auto-enable.shared.ts
+++ b/src/config/plugin-auto-enable.shared.ts
@@ -779,6 +779,7 @@ export function resolveConfiguredPluginAutoEnableCandidates(params: {
       config: params.config,
       env: params.env,
       pluginIds: setupPluginIds,
+      manifestRegistry: params.registry,
     })) {
       changes.push({
         pluginId: entry.pluginId,
diff --git a/src/gateway/server-reload-handlers.test.ts b/src/gateway/server-reload-handlers.test.ts
index 7017fc2a23f8..63a6df105fb8 100644
--- a/src/gateway/server-reload-handlers.test.ts
+++ b/src/gateway/server-reload-handlers.test.ts
@@ -5763,26 +5763,38 @@ describe("gateway plugin hot reload handlers", () => {
       stopChannel,
       reloadPlugins,
     });
+    const sourceConfig: OpenClawConfig = {
+      plugins: { enabled: false, allow: ["discord"] },
+    };
 
     try {
-      await applyHotReload(createPluginReloadPlan(), {
-        plugins: {
-          enabled: false,
+      await applyHotReload(
+        createPluginReloadPlan(),
+        {
+          plugins: {
+            enabled: false,
+          },
         },
-      });
+        {
+          sourceConfig,
+          isCurrent: () => true,
+          publish: async (commit) => await commit(),
+        },
+      );
     } finally {
       restoreChannelReloadEnv();
     }
 
     const [reloadParams] = reloadPlugins.mock.calls.at(-1) ?? [];
     const reloadParamsRecord = reloadParams as
-      | { nextConfig?: unknown; changedPaths?: unknown }
+      | { nextConfig?: unknown; sourceConfig?: unknown; changedPaths?: unknown }
       | undefined;
     expect(reloadParamsRecord?.nextConfig).toEqual({
       plugins: {
         enabled: false,
       },
     });
+    expect(reloadParamsRecord?.sourceConfig).toBe(sourceConfig);
     expect(reloadParamsRecord?.changedPaths).toEqual(["plugins.enabled"]);
     expect(stopChannel).toHaveBeenCalledWith("discord", undefined, { manual: false });
     expect(startChannel).not.toHaveBeenCalled();
diff --git a/src/plugins/bundled-manifest-contract-plugins.ts b/src/plugins/bundled-manifest-contract-plugins.ts
index e74b5157d20e..e24c6ed6a984 100644
--- a/src/plugins/bundled-manifest-contract-plugins.ts
+++ b/src/plugins/bundled-manifest-contract-plugins.ts
@@ -32,14 +32,15 @@ export function resolveEnabledBundledManifestContractPlugins(params: {
   env?: NodeJS.ProcessEnv;
   onlyPluginIds?: readonly string[];
   contract: PluginManifestContractListKey;
+  manifestRecords?: readonly PluginManifestRecord[];
 }): PluginManifestRecord[] {
   if (params.config?.plugins?.enabled === false) {
     return [];
   }
-  let manifestRecords: readonly PluginManifestRecord[] | undefined;
-  const loadManifestRecords = (config?: OpenClawConfig) => {
+  let manifestRecords = params.manifestRecords;
+  const loadManifestRecords = () => {
     manifestRecords ??= loadManifestContractSnapshot({
-      config,
+      config: params.config,
       workspaceDir: params.workspaceDir,
       env: params.env,
     }).plugins;
@@ -54,13 +55,13 @@ export function resolveEnabledBundledManifestContractPlugins(params: {
     applyAutoEnable: true,
     resolveBundledPluginIds: (compatParams) =>
       listBundledManifestContractPluginIds({
-        plugins: loadManifestRecords(compatParams.config),
+        plugins: loadManifestRecords(),
         contract: params.contract,
         onlyPluginIds: compatParams.onlyPluginIds,
       }),
   });
   const onlyPluginIdSet = createPluginIdScopeSet(params.onlyPluginIds);
-  return loadManifestRecords(activation.config).filter((plugin) => {
+  return loadManifestRecords().filter((plugin) => {
     if (
       plugin.origin !== "bundled" ||
       (onlyPluginIdSet && !onlyPluginIdSet.has(plugin.id)) ||
diff --git a/src/plugins/manifest-contract-eligibility.test.ts b/src/plugins/manifest-contract-eligibility.test.ts
index 9322bb5aefd4..93de6d0416f3 100644
--- a/src/plugins/manifest-contract-eligibility.test.ts
+++ b/src/plugins/manifest-contract-eligibility.test.ts
@@ -270,7 +270,7 @@ describe("loadManifestContractSnapshot", () => {
     expect(mocks.loadPluginMetadataSnapshot).not.toHaveBeenCalled();
   });
 
-  it("normalizes omitted config before checking unscoped snapshot compatibility", () => {
+  it("preserves configless default-discovery snapshot compatibility", () => {
     const env = { HOME: "/home/default-config" } as NodeJS.ProcessEnv;
     const snapshot = {
       index: { plugins: [{ pluginId: "demo" }] },
@@ -284,12 +284,12 @@ describe("loadManifestContractSnapshot", () => {
     });
 
     expect(mocks.resolvePluginMetadataSnapshot).toHaveBeenCalledWith({
-      config: {},
+      config: undefined,
       env,
       allowWorkspaceScopedCurrent: true,
     });
     expect(mocks.loadPluginMetadataSnapshot).toHaveBeenCalledWith({
-      config: {},
+      config: undefined,
       env,
       allowWorkspaceScopedCurrent: true,
     });
diff --git a/src/plugins/manifest-contract-eligibility.ts b/src/plugins/manifest-contract-eligibility.ts
index 2e6139fd874f..68af8eb7bee9 100644
--- a/src/plugins/manifest-contract-eligibility.ts
+++ b/src/plugins/manifest-contract-eligibility.ts
@@ -155,11 +155,9 @@ export function loadManifestMetadataSnapshot(params: {
   workspaceDir?: string;
   env?: NodeJS.ProcessEnv;
 }): PluginMetadataSnapshot {
-  const config = params.config ?? {};
-  const env = params.env ?? process.env;
   return resolvePluginMetadataSnapshot({
-    config,
-    env,
+    config: params.config,
+    env: params.env ?? process.env,
     ...(params.workspaceDir ? { workspaceDir: params.workspaceDir } : {}),
     allowWorkspaceScopedCurrent: params.workspaceDir === undefined,
   });
diff --git a/src/plugins/plugin-registry-contributions.current-snapshot.test.ts b/src/plugins/plugin-registry-contributions.current-snapshot.test.ts
index ff0651416b43..fabbda6331d5 100644
--- a/src/plugins/plugin-registry-contributions.current-snapshot.test.ts
+++ b/src/plugins/plugin-registry-contributions.current-snapshot.test.ts
@@ -5,13 +5,19 @@ import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { setCurrentPluginMetadataSnapshot } from "./current-plugin-metadata-snapshot.js";
 import { resolveInstalledPluginIndexPolicyHash } from "./installed-plugin-index-policy.js";
 import type { InstalledPluginIndex } from "./installed-plugin-index.js";
+import { loadManifestMetadataSnapshot } from "./manifest-contract-eligibility.js";
 import type { PluginManifestRecord } from "./manifest-registry.js";
 import { clearPluginMetadataLifecycleCaches } from "./plugin-metadata-lifecycle.js";
 import type { PluginMetadataSnapshot } from "./plugin-metadata-snapshot.types.js";
-import { loadPluginManifestRegistryForPluginRegistry } from "./plugin-registry-contributions.js";
+import {
+  loadPluginManifestRegistryForPluginRegistry,
+  resolveManifestContractOwnerPluginId,
+  resolveManifestContractPluginIds,
+} from "./plugin-registry-contributions.js";
 import { loadPluginRegistrySnapshotWithMetadata } from "./plugin-registry-snapshot.js";
 
 afterEach(() => {
+  vi.restoreAllMocks();
   clearPluginMetadataLifecycleCaches();
 });
 
@@ -40,7 +46,7 @@ function createManifest(id: string): PluginManifestRecord {
     channels: [],
     channelConfigs: {},
     cliBackends: [],
-    contracts: {},
+    contracts: { webSearchProviders: [`${id}-search`] },
   } as unknown as PluginManifestRecord;
 }
 
@@ -95,6 +101,74 @@ function createSnapshot(params: {
 }
 
 describe("loadPluginManifestRegistryForPluginRegistry current snapshot", () => {
+  it("reuses an allowlisted published snapshot for configless manifest reads", () => {
+    const config: OpenClawConfig = { plugins: { allow: ["enabled"] } };
+    const env = {
+      HOME: "/tmp/openclaw-test-home",
+      OPENCLAW_DISABLE_BUNDLED_PLUGINS: "1",
+    };
+    const workspaceDir = "/workspace";
+    const snapshot = createSnapshot({ config, workspaceDir });
+    setCurrentPluginMetadataSnapshot(snapshot, { config, env, workspaceDir });
+    const readDirectory = vi.spyOn(fs, "readdirSync");
+    const readFile = vi.spyOn(fs, "readFileSync");
+
+    expect(loadManifestMetadataSnapshot({ env })).toBe(snapshot);
+    expect(readDirectory).not.toHaveBeenCalled();
+    expect(readFile).not.toHaveBeenCalled();
+  });
+
+  it("projects supplied contract manifests without dropping disabled owners", () => {
+    const config: OpenClawConfig = { plugins: { allow: ["enabled"] } };
+    const env = {
+      HOME: "/tmp/openclaw-test-home",
+      OPENCLAW_DISABLE_BUNDLED_PLUGINS: "1",
+    };
+    const workspaceDir = "/workspace";
+    const snapshot = createSnapshot({ config, workspaceDir });
+    setCurrentPluginMetadataSnapshot(snapshot, { config, env, workspaceDir });
+    const readDirectory = vi.spyOn(fs, "readdirSync");
+    const readFile = vi.spyOn(fs, "readFileSync");
+
+    expect(
+      resolveManifestContractPluginIds({
+        contract: "webSearchProviders",
+        config,
+        env,
+        workspaceDir,
+      }),
+    ).toEqual(["disabled", "enabled"]);
+    expect(
+      resolveManifestContractOwnerPluginId({
+        contract: "webSearchProviders",
+        value: " DISABLED-SEARCH ",
+        config,
+        env,
+        workspaceDir,
+      }),
+    ).toBe("disabled");
+    expect(
+      resolveManifestContractPluginIds({
+        contract: "webSearchProviders",
+        config: { plugins: { allow: ["incompatible-policy"] } },
+        env,
+        manifestRecords: snapshot.plugins,
+        onlyPluginIds: ["disabled"],
+      }),
+    ).toEqual(["disabled"]);
+    expect(
+      resolveManifestContractOwnerPluginId({
+        contract: "webSearchProviders",
+        value: "disabled-search",
+        config: { plugins: { allow: ["incompatible-policy"] } },
+        env,
+        manifestRecords: snapshot.plugins,
+      }),
+    ).toBe("disabled");
+    expect(readDirectory).not.toHaveBeenCalled();
+    expect(readFile).not.toHaveBeenCalled();
+  });
+
   it("reuses compatible current manifest metadata", () => {
     const config: OpenClawConfig = {};
     const env = {
diff --git a/src/plugins/plugin-registry-contributions.ts b/src/plugins/plugin-registry-contributions.ts
index 157dd3cd5e70..60091f883777 100644
--- a/src/plugins/plugin-registry-contributions.ts
+++ b/src/plugins/plugin-registry-contributions.ts
@@ -13,6 +13,7 @@ import type {
   PluginManifestRecord,
   PluginManifestRegistry,
 } from "./manifest-registry.js";
+import { resolvePluginMetadataSnapshot } from "./plugin-metadata-snapshot.js";
 import type { PluginMetadataSnapshot } from "./plugin-metadata-snapshot.types.js";
 import type { PluginOrigin } from "./plugin-origin.types.js";
 import {
@@ -62,13 +63,17 @@ type ListPluginContributionIdsParams = PluginRegistryContributionOptions & {
   contribution: PluginRegistryContributionKey;
 };
 
-type ResolveManifestContractPluginIdsParams = LoadPluginRegistryParams & {
+type ManifestContractLookupParams = LoadPluginRegistryParams & {
+  manifestRecords?: readonly PluginManifestRecord[];
+};
+
+type ResolveManifestContractPluginIdsParams = ManifestContractLookupParams & {
   contract: PluginManifestContractListKey;
   origin?: PluginOrigin;
   onlyPluginIds?: readonly string[];
 };
 
-type ResolveManifestContractOwnerPluginIdParams = LoadPluginRegistryParams & {
+type ResolveManifestContractOwnerPluginIdParams = ManifestContractLookupParams & {
   contract: PluginManifestContractListKey;
   value: string | undefined;
   origin?: PluginOrigin;
@@ -99,16 +104,44 @@ function listManifestContractValues(
   return plugin.contracts?.[contract] ?? [];
 }
 
-function loadManifestContractRegistry(
-  params: LoadPluginRegistryParams & {
+function loadManifestContractRecords(
+  params: ManifestContractLookupParams & {
     onlyPluginIds?: readonly string[];
   },
-): PluginManifestRegistry {
-  return loadPluginManifestRegistryForPluginRegistry({
-    ...params,
-    pluginIds: params.onlyPluginIds,
-    includeDisabled: true,
-  });
+): readonly PluginManifestRecord[] {
+  let records = params.manifestRecords;
+  if (!records) {
+    const requiresExplicitRegistry =
+      params.index !== undefined ||
+      params.preferPersisted === false ||
+      params.allowCurrent === false ||
+      params.stateDir !== undefined ||
+      params.filePath !== undefined ||
+      params.pluginIndexFilePath !== undefined ||
+      params.installRecords !== undefined ||
+      params.candidates !== undefined ||
+      params.diagnostics !== undefined ||
+      params.discovery !== undefined ||
+      params.now !== undefined;
+    if (requiresExplicitRegistry) {
+      return loadPluginManifestRegistryForPluginRegistry({
+        ...params,
+        pluginIds: params.onlyPluginIds,
+        includeDisabled: true,
+      }).plugins;
+    }
+    records = resolvePluginMetadataSnapshot({
+      config: params.config,
+      env: params.env,
+      ...(params.workspaceDir !== undefined ? { workspaceDir: params.workspaceDir } : {}),
+      allowWorkspaceScopedCurrent: params.workspaceDir === undefined,
+    }).plugins;
+  }
+  if (params.onlyPluginIds === undefined) {
+    return records;
+  }
+  const pluginIds = new Set(params.onlyPluginIds);
+  return records.filter((record) => pluginIds.has(record.id));
 }
 
 function listManifestContributionIds(
@@ -308,8 +341,8 @@ export function resolvePluginContributionOwners(
 export function resolveManifestContractPluginIds(
   params: ResolveManifestContractPluginIdsParams,
 ): string[] {
-  return loadManifestContractRegistry(params)
-    .plugins.filter(
+  return loadManifestContractRecords(params)
+    .filter(
       (plugin) =>
         (!params.origin || plugin.origin === params.origin) &&
         listManifestContractValues(plugin, params.contract).length > 0,
@@ -325,7 +358,7 @@ export function resolveManifestContractOwnerPluginId(
   if (!normalizedValue) {
     return undefined;
   }
-  return loadManifestContractRegistry(params).plugins.find(
+  return loadManifestContractRecords(params).find(
     (plugin) =>
       (!params.origin || plugin.origin === params.origin) &&
       listManifestContractValues(plugin, params.contract).some(
diff --git a/src/plugins/web-fetch-providers.runtime.ts b/src/plugins/web-fetch-providers.runtime.ts
index d50086b40ac2..b03d3117dcd0 100644
--- a/src/plugins/web-fetch-providers.runtime.ts
+++ b/src/plugins/web-fetch-providers.runtime.ts
@@ -27,6 +27,7 @@ function resolveWebFetchCandidatePluginIds(params: {
   onlyPluginIds?: readonly string[];
   origin?: PluginManifestRecord["origin"];
   sandboxed?: boolean;
+  manifestRecords?: readonly PluginManifestRecord[];
 }): string[] | undefined {
   return resolveManifestDeclaredWebProviderCandidatePluginIds({
     contract: "webFetchProviders",
@@ -37,6 +38,7 @@ function resolveWebFetchCandidatePluginIds(params: {
     onlyPluginIds: params.onlyPluginIds,
     origin: params.origin,
     sandboxed: params.sandboxed,
+    manifestRecords: params.manifestRecords,
   });
 }
 
@@ -62,6 +64,7 @@ export function resolvePluginWebFetchProviders(params: {
   mode?: "runtime" | "setup";
   origin?: PluginManifestRecord["origin"];
   sandboxed?: boolean;
+  manifestRecords?: readonly PluginManifestRecord[];
 }): PluginWebFetchProviderEntry[] {
   return resolvePluginWebProviders(params, {
     resolveBundledResolutionConfig: resolveBundledWebFetchResolutionConfig,
@@ -80,6 +83,7 @@ export function resolveRuntimeWebFetchProviders(params: {
   env?: PluginLoadOptions["env"];
   onlyPluginIds?: readonly string[];
   origin?: PluginManifestRecord["origin"];
+  manifestRecords?: readonly PluginManifestRecord[];
 }): PluginWebFetchProviderEntry[] {
   return resolveRuntimeWebProviders(params, {
     resolveBundledResolutionConfig: resolveBundledWebFetchResolutionConfig,
diff --git a/src/plugins/web-fetch-providers.shared.ts b/src/plugins/web-fetch-providers.shared.ts
index f7047cd8ec09..56f45d5f1b28 100644
--- a/src/plugins/web-fetch-providers.shared.ts
+++ b/src/plugins/web-fetch-providers.shared.ts
@@ -1,5 +1,6 @@
 // Shares web fetch provider loading helpers across provider plugins.
 import type { PluginLoadOptions } from "./loader.js";
+import type { PluginManifestRecord } from "./manifest-registry.js";
 import type { PluginWebFetchProviderEntry } from "./types.js";
 import {
   resolveBundledWebProviderResolutionConfig,
@@ -23,15 +24,18 @@ export function resolveBundledWebFetchResolutionConfig(params: {
   config?: PluginLoadOptions["config"];
   workspaceDir?: string;
   env?: PluginLoadOptions["env"];
+  manifestRecords?: readonly PluginManifestRecord[];
 }): {
   config: PluginLoadOptions["config"];
   activationSourceConfig?: PluginLoadOptions["config"];
   autoEnabledReasons: Record<string, string[]>;
+  manifestRecords?: readonly PluginManifestRecord[];
 } {
   return resolveBundledWebProviderResolutionConfig({
     contract: "webFetchProviders",
     config: params.config,
     workspaceDir: params.workspaceDir,
     env: params.env,
+    manifestRecords: params.manifestRecords,
   });
 }
diff --git a/src/plugins/web-provider-public-artifacts.ts b/src/plugins/web-provider-public-artifacts.ts
index 972b6df763fa..c520f05b121c 100644
--- a/src/plugins/web-provider-public-artifacts.ts
+++ b/src/plugins/web-provider-public-artifacts.ts
@@ -6,6 +6,7 @@ import { resolveEnabledBundledManifestContractPlugins } from "./bundled-manifest
 import { normalizePluginId } from "./config-state.js";
 import type { PluginLoadOptions } from "./loader.js";
 import { loadManifestMetadataSnapshot } from "./manifest-contract-eligibility.js";
+import type { PluginManifestRecord } from "./manifest-registry.js";
 import type { PluginWebFetchProviderEntry, PluginWebSearchProviderEntry } from "./types.js";
 import { resolveBundledWebFetchResolutionConfig } from "./web-fetch-providers.shared.js";
 import {
@@ -23,6 +24,7 @@ type BundledWebProviderPublicArtifactParams = {
   workspaceDir?: string;
   env?: PluginLoadOptions["env"];
   onlyPluginIds?: readonly string[];
+  manifestRecords?: readonly PluginManifestRecord[];
 };
 
 function filterAllowlistedBundledPluginIds(
@@ -51,12 +53,14 @@ function resolveBundledCandidatePluginIds(params: {
   workspaceDir?: string;
   env?: PluginLoadOptions["env"];
   onlyPluginIds?: readonly string[];
+  manifestRecords?: readonly PluginManifestRecord[];
 }) {
   if (params.onlyPluginIds !== undefined) {
     return {
       pluginIds: filterAllowlistedBundledPluginIds(params.config, [
         ...new Set(params.onlyPluginIds),
       ]).toSorted((left, right) => left.localeCompare(right)),
+      ...(params.manifestRecords ? { manifestRecords: params.manifestRecords } : {}),
     };
   }
   const resolvedConfig =
@@ -66,11 +70,12 @@ function resolveBundledCandidatePluginIds(params: {
   const candidates = resolveManifestDeclaredWebProviderCandidates({
     contract: params.contract,
     configKey: params.configKey,
-    config: resolvedConfig,
+    config: params.config,
     workspaceDir: params.workspaceDir,
     env: params.env,
     onlyPluginIds: params.onlyPluginIds,
     origin: "bundled",
+    manifestRecords: params.manifestRecords,
   });
   return {
     pluginIds: filterAllowlistedBundledPluginIds(resolvedConfig, candidates.pluginIds ?? []),
@@ -83,15 +88,17 @@ function resolveBundledRuntimeCandidatePluginIds(params: {
   workspaceDir?: string;
   env?: PluginLoadOptions["env"];
   onlyPluginIds: readonly string[];
+  manifestRecords?: readonly PluginManifestRecord[];
 }): string[] | null {
   const resolvedConfig = resolveBundledWebFetchResolutionConfig(params).config;
   const candidates = resolveManifestDeclaredWebProviderCandidates({
     contract: "webFetchProviders",
     configKey: "webFetch",
-    config: resolvedConfig,
+    config: params.config,
     workspaceDir: params.workspaceDir,
     env: params.env,
     onlyPluginIds: params.onlyPluginIds,
+    manifestRecords: params.manifestRecords,
   });
   const pluginIds = filterAllowlistedBundledPluginIds(resolvedConfig, candidates.pluginIds ?? []);
   const recordsByPluginId = new Map(
@@ -109,6 +116,7 @@ function resolveBundledRuntimeCandidatePluginIds(params: {
       env: params.env,
       onlyPluginIds: pluginIds,
       contract: "webFetchProviders",
+      manifestRecords: candidates.manifestRecords,
     }).map((plugin) => plugin.id),
   );
   return pluginIds.filter((pluginId) => enabledPluginIds.has(pluginId));
@@ -128,6 +136,7 @@ function resolveBundledWebProvidersFromPublicArtifacts<TProvider>(params: {
     workspaceDir: params.resolution.workspaceDir,
     env: params.resolution.env,
     onlyPluginIds: params.resolution.onlyPluginIds,
+    manifestRecords: params.resolution.manifestRecords,
   });
   if (candidates.pluginIds.length === 0) {
     return [];
@@ -142,6 +151,7 @@ function resolveBundledWebProvidersFromPublicArtifacts<TProvider>(params: {
   const recordsByPluginId = new Map(
     (
       candidates.manifestRecords ??
+      params.resolution.manifestRecords ??
       loadManifestMetadataSnapshot({
         config: params.resolution.config,
         workspaceDir: params.resolution.workspaceDir,
@@ -205,6 +215,7 @@ export function resolveBundledRuntimeWebFetchProvidersFromPublicArtifacts(
     workspaceDir: params.workspaceDir,
     env: params.env,
     onlyPluginIds: params.onlyPluginIds,
+    manifestRecords: params.manifestRecords,
   });
   if (!pluginIds) {
     return null;
diff --git a/src/plugins/web-provider-resolution-shared.ts b/src/plugins/web-provider-resolution-shared.ts
index 86f3770770a5..2c51822856b6 100644
--- a/src/plugins/web-provider-resolution-shared.ts
+++ b/src/plugins/web-provider-resolution-shared.ts
@@ -1,5 +1,6 @@
 // Shares web-provider plugin resolution helpers without eager runtime imports.
 import { resolveBundledCompatActivationInputs } from "./activation-context.js";
+import { getCurrentPluginMetadataSnapshot } from "./current-plugin-metadata-snapshot.js";
 import type { PluginLoadOptions } from "./loader.js";
 import { loadManifestMetadataSnapshot } from "./manifest-contract-eligibility.js";
 import type { PluginManifestRecord } from "./manifest-registry.js";
@@ -68,12 +69,15 @@ function loadInstalledWebProviderManifestRecords(params: {
   workspaceDir?: string;
   env?: PluginLoadOptions["env"];
   pluginIds?: readonly string[];
+  manifestRecords?: readonly PluginManifestRecord[];
 }): readonly PluginManifestRecord[] {
-  const records = loadManifestMetadataSnapshot({
-    config: params.config ?? {},
-    workspaceDir: params.workspaceDir,
-    env: params.env ?? process.env,
-  }).plugins;
+  const records =
+    params.manifestRecords ??
+    loadManifestMetadataSnapshot({
+      config: params.config,
+      workspaceDir: params.workspaceDir,
+      env: params.env ?? process.env,
+    }).plugins;
   const pluginIdSet = createPluginIdScopeSet(params.pluginIds);
   return pluginIdSet ? records.filter((plugin) => pluginIdSet.has(plugin.id)) : records;
 }
@@ -88,6 +92,7 @@ export function resolveManifestDeclaredWebProviderCandidatePluginIds(params: {
   onlyPluginIds?: readonly string[];
   origin?: PluginManifestRecord["origin"];
   sandboxed?: boolean;
+  manifestRecords?: readonly PluginManifestRecord[];
 }): string[] | undefined {
   return resolveManifestDeclaredWebProviderCandidates(params).pluginIds;
 }
@@ -147,6 +152,7 @@ function resolveBundledWebProviderCompatPluginIds(params: {
   config?: PluginLoadOptions["config"];
   workspaceDir?: string;
   env?: PluginLoadOptions["env"];
+  manifestRecords?: readonly PluginManifestRecord[];
 }): string[] {
   return loadInstalledWebProviderManifestRecords(params)
     .filter(
@@ -163,27 +169,48 @@ export function resolveBundledWebProviderResolutionConfig(params: {
   config?: PluginLoadOptions["config"];
   workspaceDir?: string;
   env?: PluginLoadOptions["env"];
+  manifestRecords?: readonly PluginManifestRecord[];
 }): {
   config: PluginLoadOptions["config"];
   activationSourceConfig?: PluginLoadOptions["config"];
   autoEnabledReasons: Record<string, string[]>;
+  manifestRecords?: readonly PluginManifestRecord[];
 } {
+  const currentSnapshot = getCurrentPluginMetadataSnapshot({
+    config: params.config,
+    env: params.env,
+    workspaceDir: params.workspaceDir,
+    allowWorkspaceScopedSnapshot: true,
+  });
+  let manifestRecords = params.manifestRecords ?? currentSnapshot?.plugins;
   const activation = resolveBundledCompatActivationInputs({
     rawConfig: params.config,
     env: params.env,
     workspaceDir: params.workspaceDir,
     applyAutoEnable: true,
-    resolveBundledPluginIds: (compatParams) =>
-      resolveBundledWebProviderCompatPluginIds({
+    ...(manifestRecords
+      ? { manifestRegistry: { plugins: [...manifestRecords], diagnostics: [] } }
+      : {}),
+    ...(currentSnapshot?.discovery ? { discovery: currentSnapshot.discovery } : {}),
+    resolveBundledPluginIds: (compatParams) => {
+      manifestRecords ??= loadInstalledWebProviderManifestRecords({
+        config: params.config,
+        workspaceDir: params.workspaceDir,
+        env: params.env,
+      });
+      return resolveBundledWebProviderCompatPluginIds({
         contract: params.contract,
         ...compatParams,
-      }),
+        manifestRecords,
+      });
+    },
   });
 
   return {
     config: activation.config,
     activationSourceConfig: activation.activationSourceConfig,
     autoEnabledReasons: activation.autoEnabledReasons,
+    manifestRecords,
   };
 }
 
diff --git a/src/plugins/web-provider-runtime-shared.test.ts b/src/plugins/web-provider-runtime-shared.test.ts
index ed311ce64d71..24cf0c3ef248 100644
--- a/src/plugins/web-provider-runtime-shared.test.ts
+++ b/src/plugins/web-provider-runtime-shared.test.ts
@@ -1,6 +1,7 @@
 // Covers shared web provider runtime helpers.
 import { createRequireRecord } from "openclaw/plugin-sdk/test-fixtures";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PluginManifestRecord } from "./manifest-registry.js";
 
 const mocks = vi.hoisted(() => ({
   isPluginRegistryLoadInFlight: vi.fn(() => false),
@@ -156,27 +157,31 @@ describe("web-provider-runtime-shared", () => {
     expect(mockArg(mapRegistryProviders).onlyPluginIds).toEqual(["alpha"]);
   });
 
-  it("reuses the active registry after deriving web provider candidates from resolved config", () => {
+  it("resolves provider candidates from the original config and prepared manifests", () => {
     const activeRegistry = { source: "active" };
+    const config = { plugins: { entries: {} } };
     const resolvedConfig = { plugins: { entries: { brave: { enabled: true } } } };
+    const manifestRecords: PluginManifestRecord[] = [];
     const resolveCandidatePluginIds = vi.fn(() => ["brave"]);
     const mapRegistryProviders = vi.fn(() => ["provider"]);
     mocks.getLoadedRuntimePluginRegistry.mockReturnValue(activeRegistry);
 
     const providers = resolvePluginWebProviders(
       {
-        config: { plugins: { entries: {} } },
+        config,
         env: { BRAVE_API_KEY: "key" },
         onlyPluginIds: ["brave", "firecrawl"],
         origin: "bundled",
         sandboxed: true,
         workspaceDir: "/workspace",
+        manifestRecords,
       },
       {
         resolveBundledResolutionConfig: () => ({
           config: resolvedConfig,
-          activationSourceConfig: { plugins: { entries: {} } },
+          activationSourceConfig: config,
           autoEnabledReasons: { brave: ["env"] },
+          manifestRecords,
         }),
         resolveCandidatePluginIds,
         mapRegistryProviders,
@@ -185,17 +190,22 @@ describe("web-provider-runtime-shared", () => {
 
     expect(providers).toEqual(["provider"]);
     expect(resolveCandidatePluginIds).toHaveBeenCalledWith({
-      config: resolvedConfig,
+      config,
       workspaceDir: "/workspace",
       env: { BRAVE_API_KEY: "key" },
       onlyPluginIds: ["brave", "firecrawl"],
       origin: "bundled",
       sandboxed: true,
+      manifestRecords,
     });
     expect(mapRegistryProviders).toHaveBeenCalledWith({
       registry: activeRegistry,
       onlyPluginIds: ["brave"],
     });
+    expect(mockArg(mocks.buildPluginRuntimeLoadOptionsFromValues).manifestRegistry).toEqual({
+      plugins: manifestRecords,
+      diagnostics: [],
+    });
     expect(mocks.loadOpenClawPlugins).not.toHaveBeenCalled();
   });
 
diff --git a/src/plugins/web-provider-runtime-shared.ts b/src/plugins/web-provider-runtime-shared.ts
index 9d3ddbc8ad5d..485b39649b9a 100644
--- a/src/plugins/web-provider-runtime-shared.ts
+++ b/src/plugins/web-provider-runtime-shared.ts
@@ -1,9 +1,10 @@
 // Shares web provider runtime helpers across plugin-owned providers.
 import { withActivatedPluginIds } from "./activation-context.js";
 import { getLoadedRuntimePluginRegistry } from "./active-runtime-registry.js";
+import { normalizePluginId } from "./config-state.js";
 import { isPluginRegistryLoadInFlight, loadOpenClawPlugins } from "./loader.js";
 import type { PluginLoadOptions } from "./loader.js";
-import type { PluginManifestRecord } from "./manifest-registry.js";
+import type { PluginManifestRecord, PluginManifestRegistry } from "./manifest-registry.js";
 import { hasExplicitPluginIdScope, normalizePluginIdScope } from "./plugin-scope.js";
 import type { PluginRegistry } from "./registry.js";
 import { getActivePluginRegistryWorkspaceDir } from "./runtime.js";
@@ -23,6 +24,7 @@ type ResolvePluginWebProvidersParams = {
   mode?: "runtime" | "setup";
   origin?: PluginManifestRecord["origin"];
   sandboxed?: boolean;
+  manifestRecords?: readonly PluginManifestRecord[];
 };
 
 type ResolveWebProviderRuntimeDeps<TEntry> = {
@@ -30,10 +32,12 @@ type ResolveWebProviderRuntimeDeps<TEntry> = {
     config?: PluginLoadOptions["config"];
     workspaceDir?: string;
     env?: PluginLoadOptions["env"];
+    manifestRecords?: readonly PluginManifestRecord[];
   }) => {
     config: PluginLoadOptions["config"];
     activationSourceConfig?: PluginLoadOptions["config"];
     autoEnabledReasons: Record<string, string[]>;
+    manifestRecords?: readonly PluginManifestRecord[];
   };
   resolveCandidatePluginIds: (params: {
     config?: PluginLoadOptions["config"];
@@ -42,6 +46,7 @@ type ResolveWebProviderRuntimeDeps<TEntry> = {
     onlyPluginIds?: readonly string[];
     origin?: PluginManifestRecord["origin"];
     sandboxed?: boolean;
+    manifestRecords?: readonly PluginManifestRecord[];
   }) => string[] | undefined;
   mapRegistryProviders: (params: {
     registry: PluginRegistry;
@@ -52,12 +57,14 @@ type ResolveWebProviderRuntimeDeps<TEntry> = {
     workspaceDir?: string;
     env?: PluginLoadOptions["env"];
     onlyPluginIds?: readonly string[];
+    manifestRecords?: readonly PluginManifestRecord[];
   }) => TEntry[] | null;
   resolveBundledRuntimeArtifactProviders?: (params: {
     config?: PluginLoadOptions["config"];
     workspaceDir?: string;
     env?: PluginLoadOptions["env"];
     onlyPluginIds: readonly string[];
+    manifestRecords?: readonly PluginManifestRecord[];
   }) => TEntry[] | null;
 };
 
@@ -67,6 +74,8 @@ type WebProviderRuntimeContext = {
   config: PluginLoadOptions["config"];
   activationSourceConfig?: PluginLoadOptions["config"];
   autoEnabledReasons: Record<string, string[]>;
+  manifestRecords?: readonly PluginManifestRecord[];
+  preparedManifestRegistry?: PluginManifestRegistry;
   loadPluginIds?: string[];
   onlyPluginIds?: string[];
 };
@@ -87,27 +96,42 @@ function resolveWebProviderRuntimeContext<TEntry>(
     params.onlyPluginIds !== undefined ||
     params.origin !== undefined ||
     params.sandboxed === true;
-  const { config, activationSourceConfig, autoEnabledReasons } =
+  const { config, activationSourceConfig, autoEnabledReasons, manifestRecords } =
     deps.resolveBundledResolutionConfig({
       ...params,
       workspaceDir,
       env,
     });
-  const candidatePluginIds = normalizePluginIdScope(
+  const discoveredPluginIds = normalizePluginIdScope(
     deps.resolveCandidatePluginIds({
-      config,
+      config: params.config,
       workspaceDir,
       env,
       onlyPluginIds: params.onlyPluginIds,
       origin: params.origin,
       sandboxed: params.sandboxed,
+      ...(manifestRecords ? { manifestRecords } : {}),
     }),
   );
+  const allowedPluginIds = config?.plugins?.allow;
+  const allowSet = allowedPluginIds?.length
+    ? new Set(allowedPluginIds.map((pluginId) => normalizePluginId(pluginId)))
+    : undefined;
+  const allowlistedPluginIds = allowSet
+    ? discoveredPluginIds?.filter((pluginId) => allowSet.has(normalizePluginId(pluginId)))
+    : discoveredPluginIds;
+  const candidatePluginIds = allowlistedPluginIds?.length
+    ? allowlistedPluginIds
+    : discoveredPluginIds;
   return {
     activationSourceConfig,
     autoEnabledReasons,
     config,
     env,
+    manifestRecords,
+    ...(params.manifestRecords
+      ? { preparedManifestRegistry: { plugins: [...params.manifestRecords], diagnostics: [] } }
+      : {}),
     loadPluginIds: candidatePluginIds,
     onlyPluginIds: shouldFilterProviders ? candidatePluginIds : undefined,
     workspaceDir,
@@ -126,6 +150,9 @@ function resolveWebProviderLoadOptions(
       autoEnabledReasons: context.autoEnabledReasons,
       workspaceDir: context.workspaceDir,
       logger: createPluginRuntimeLoaderLogger(),
+      ...(context.preparedManifestRegistry
+        ? { manifestRegistry: context.preparedManifestRegistry }
+        : {}),
     },
     {
       cache: params.cache ?? true,
@@ -172,6 +199,7 @@ export function resolvePluginWebProviders<TEntry>(
         onlyPluginIds: params.onlyPluginIds,
         origin: params.origin,
         sandboxed: params.sandboxed,
+        ...(params.manifestRecords ? { manifestRecords: params.manifestRecords } : {}),
       }) ?? [];
     if (pluginIds.length === 0) {
       return [];
@@ -182,6 +210,7 @@ export function resolvePluginWebProviders<TEntry>(
         workspaceDir,
         env,
         onlyPluginIds: pluginIds,
+        ...(params.manifestRecords ? { manifestRecords: params.manifestRecords } : {}),
       });
       if (bundledArtifactProviders) {
         return bundledArtifactProviders;
@@ -199,6 +228,9 @@ export function resolvePluginWebProviders<TEntry>(
           workspaceDir,
           env,
           logger: createPluginRuntimeLoaderLogger(),
+          ...(params.manifestRecords
+            ? { manifestRegistry: { plugins: [...params.manifestRecords], diagnostics: [] } }
+            : {}),
         },
         {
           onlyPluginIds: pluginIds,
@@ -253,6 +285,7 @@ export function resolvePluginWebProviders<TEntry>(
       workspaceDir: context.workspaceDir,
       env: context.env,
       onlyPluginIds: context.loadPluginIds,
+      ...(context.manifestRecords ? { manifestRecords: context.manifestRecords } : {}),
     });
     if (bundledArtifactProviders) {
       return bundledArtifactProviders;
diff --git a/src/plugins/web-search-providers.runtime.ts b/src/plugins/web-search-providers.runtime.ts
index c0a5caa9a6d0..d541354cb1b9 100644
--- a/src/plugins/web-search-providers.runtime.ts
+++ b/src/plugins/web-search-providers.runtime.ts
@@ -23,6 +23,7 @@ function resolveWebSearchCandidatePluginIds(params: {
   env?: PluginLoadOptions["env"];
   onlyPluginIds?: readonly string[];
   origin?: PluginManifestRecord["origin"];
+  manifestRecords?: readonly PluginManifestRecord[];
 }): string[] | undefined {
   return resolveManifestDeclaredWebProviderCandidatePluginIds({
     contract: "webSearchProviders",
@@ -32,6 +33,7 @@ function resolveWebSearchCandidatePluginIds(params: {
     env: params.env,
     onlyPluginIds: params.onlyPluginIds,
     origin: params.origin,
+    manifestRecords: params.manifestRecords,
   });
 }
 
@@ -55,6 +57,7 @@ export function resolvePluginWebSearchProviders(params: {
   cache?: boolean;
   mode?: "runtime" | "setup";
   origin?: PluginManifestRecord["origin"];
+  manifestRecords?: readonly PluginManifestRecord[];
 }): PluginWebSearchProviderEntry[] {
   return resolvePluginWebProviders(params, {
     resolveBundledResolutionConfig: resolveBundledWebSearchResolutionConfig,
@@ -70,6 +73,7 @@ export function resolveRuntimeWebSearchProviders(params: {
   env?: PluginLoadOptions["env"];
   onlyPluginIds?: readonly string[];
   origin?: PluginManifestRecord["origin"];
+  manifestRecords?: readonly PluginManifestRecord[];
 }): PluginWebSearchProviderEntry[] {
   return resolveRuntimeWebProviders(params, {
     resolveBundledResolutionConfig: resolveBundledWebSearchResolutionConfig,
diff --git a/src/plugins/web-search-providers.shared.ts b/src/plugins/web-search-providers.shared.ts
index fbfc92733cba..6bf8de210501 100644
--- a/src/plugins/web-search-providers.shared.ts
+++ b/src/plugins/web-search-providers.shared.ts
@@ -1,5 +1,6 @@
 // Shares web-search provider loading helpers across runtime paths.
 import type { PluginLoadOptions } from "./loader.js";
+import type { PluginManifestRecord } from "./manifest-registry.js";
 import type { PluginWebSearchProviderEntry } from "./types.js";
 import {
   resolveBundledWebProviderResolutionConfig,
@@ -23,15 +24,18 @@ export function resolveBundledWebSearchResolutionConfig(params: {
   config?: PluginLoadOptions["config"];
   workspaceDir?: string;
   env?: PluginLoadOptions["env"];
+  manifestRecords?: readonly PluginManifestRecord[];
 }): {
   config: PluginLoadOptions["config"];
   activationSourceConfig?: PluginLoadOptions["config"];
   autoEnabledReasons: Record<string, string[]>;
+  manifestRecords?: readonly PluginManifestRecord[];
 } {
   return resolveBundledWebProviderResolutionConfig({
     contract: "webSearchProviders",
     config: params.config,
     workspaceDir: params.workspaceDir,
     env: params.env,
+    manifestRecords: params.manifestRecords,
   });
 }
diff --git a/src/secrets/runtime-config-collectors-plugins.ts b/src/secrets/runtime-config-collectors-plugins.ts
index 0ed29b4db393..b6876a70c691 100644
--- a/src/secrets/runtime-config-collectors-plugins.ts
+++ b/src/secrets/runtime-config-collectors-plugins.ts
@@ -54,16 +54,18 @@ export function collectPluginConfigAssignments(params: {
       config: params.config,
       env: params.context.env,
     });
-  const bundledLoadablePluginIds = [...(params.loadablePluginOrigins?.entries() ?? [])]
-    .filter(([, origin]) => origin === "bundled")
-    .map(([pluginId]) => pluginId);
+  const bundledLoadablePluginIds = params.context.manifestRegistry
+    ? []
+    : [...(params.loadablePluginOrigins?.entries() ?? [])]
+        .filter(([, origin]) => origin === "bundled")
+        .map(([pluginId]) => pluginId);
   const pluginSecretInputs = new Map(
     [
       ...resolvePluginConfigContractsById({
         config: params.config,
         env: params.context.env,
         fallbackToBundledMetadata: true,
-        fallbackToBundledMetadataForResolvedBundled: true,
+        fallbackToBundledMetadataForResolvedBundled: !params.context.manifestRegistry,
         fallbackBundledPluginIds: bundledLoadablePluginIds,
         pluginIds: Object.keys(entries),
         manifestRegistry,
diff --git a/src/secrets/runtime-web-tools.shared.ts b/src/secrets/runtime-web-tools.shared.ts
index c35e35ab11b1..f79fa732d8f3 100644
--- a/src/secrets/runtime-web-tools.shared.ts
+++ b/src/secrets/runtime-web-tools.shared.ts
@@ -260,6 +260,7 @@ export async function resolveRuntimeWebProviderSurface<
       origin: "bundled",
       config: params.sourceConfig,
       env: { ...process.env, ...params.context.env },
+      manifestRecords: params.context.manifestRegistry?.plugins,
     });
   }
   let allProviders = params.sortProviders(
@@ -287,6 +288,7 @@ export async function resolveRuntimeWebProviderSurface<
       origin: "bundled",
       config: params.sourceConfig,
       env: { ...process.env, ...params.context.env },
+      manifestRecords: params.context.manifestRegistry?.plugins,
     });
     allProviders = params.sortProviders(
       await params.resolveProviders({
diff --git a/src/secrets/runtime-web-tools.ts b/src/secrets/runtime-web-tools.ts
index dc826283d353..c343726fa5ed 100644
--- a/src/secrets/runtime-web-tools.ts
+++ b/src/secrets/runtime-web-tools.ts
@@ -4,6 +4,7 @@ import { sortUniqueStrings } from "@openclaw/normalization-core/string-normaliza
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveSecretInputRef } from "../config/types.secrets.js";
 import { loadInstalledPluginIndexInstallRecordsSync } from "../plugins/installed-plugin-index-records.js";
+import type { PluginManifestRecord } from "../plugins/manifest-registry.js";
 import type {
   PluginWebFetchProviderEntry,
   PluginWebSearchProviderEntry,
@@ -367,6 +368,7 @@ async function hasCustomWebProviderPluginRisk(params: {
   contract: WebProviderContract;
   config: OpenClawConfig;
   env: NodeJS.ProcessEnv;
+  manifestRecords?: readonly PluginManifestRecord[];
 }): Promise<boolean> {
   const installRecords = loadInstalledPluginIndexInstallRecordsSync({ env: params.env });
   if (Object.keys(installRecords).length > 0) {
@@ -387,6 +389,7 @@ async function hasCustomWebProviderPluginRisk(params: {
       origin: "bundled",
       config: params.config,
       env: params.env,
+      manifestRecords: params.manifestRecords,
     }),
   );
   // Public artifacts are complete only for bundled providers. Any configured non-bundled
@@ -596,6 +599,7 @@ async function resolveBundledWebSearchProviders(params: {
       env,
       onlyPluginIds,
       origin: "bundled",
+      manifestRecords: params.context.manifestRegistry?.plugins,
     });
   }
   if (!params.hasCustomWebSearchPluginRisk) {
@@ -604,6 +608,7 @@ async function resolveBundledWebSearchProviders(params: {
     const bundled = resolveBundledWebSearchProvidersFromPublicArtifacts({
       config: params.sourceConfig,
       env,
+      manifestRecords: params.context.manifestRegistry?.plugins,
     });
     if (bundled && bundled.length > 0) {
       return bundled;
@@ -613,12 +618,14 @@ async function resolveBundledWebSearchProviders(params: {
       config: params.sourceConfig,
       env,
       origin: "bundled",
+      manifestRecords: params.context.manifestRegistry?.plugins,
     });
   }
   const { resolvePluginWebSearchProviders } = await loadRuntimeWebToolsFallbackProviders();
   return resolvePluginWebSearchProviders({
     config: params.sourceConfig,
     env,
+    manifestRecords: params.context.manifestRegistry?.plugins,
   });
 }
 
@@ -644,6 +651,7 @@ async function resolveBundledWebFetchProviders(params: {
       env,
       onlyPluginIds: [params.configuredBundledPluginId],
       origin: "bundled",
+      manifestRecords: params.context.manifestRegistry?.plugins,
     });
   }
   if (!params.hasCustomWebFetchPluginRisk) {
@@ -652,6 +660,7 @@ async function resolveBundledWebFetchProviders(params: {
     const bundled = resolveBundledWebFetchProvidersFromPublicArtifacts({
       config: params.sourceConfig,
       env,
+      manifestRecords: params.context.manifestRegistry?.plugins,
     });
     if (bundled && bundled.length > 0) {
       return bundled;
@@ -661,6 +670,7 @@ async function resolveBundledWebFetchProviders(params: {
       config: params.sourceConfig,
       env,
       origin: "bundled",
+      manifestRecords: params.context.manifestRegistry?.plugins,
     });
   }
   const { resolvePluginWebFetchProviders } = await loadRuntimeWebToolsFallbackProviders();
@@ -670,6 +680,7 @@ async function resolveBundledWebFetchProviders(params: {
     // Runtime credential resolution may load only bundled providers or verified
     // official installs. Arbitrary external providers must not gain SecretRef access.
     sandboxed: true,
+    manifestRecords: params.context.manifestRegistry?.plugins,
   });
 }
 
@@ -775,6 +786,7 @@ export async function resolveRuntimeWebTools(params: {
       contract: "webSearchProviders",
       config: params.sourceConfig,
       env,
+      manifestRecords: params.context.manifestRegistry?.plugins,
     });
     return hasCustomWebSearchRisk;
   };
@@ -784,6 +796,7 @@ export async function resolveRuntimeWebTools(params: {
       contract: "webFetchProviders",
       config: params.sourceConfig,
       env,
+      manifestRecords: params.context.manifestRegistry?.plugins,
     });
     return hasCustomWebFetchRisk;
   };
diff --git a/src/secrets/runtime.fast-path.test.ts b/src/secrets/runtime.fast-path.test.ts
index 981558db10aa..3e2b226b78e5 100644
--- a/src/secrets/runtime.fast-path.test.ts
+++ b/src/secrets/runtime.fast-path.test.ts
@@ -1,5 +1,5 @@
 /** Tests secrets runtime fast-path decisions and skip conditions. */
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import fs, { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -13,18 +13,23 @@ import { closeOpenClawAgentDatabasesForTest } from "../state/openclaw-agent-db.j
 import { clearSecretsRuntimeSnapshot } from "./runtime.js";
 import { asConfig } from "./runtime.test-support.js";
 
-const { resolveRuntimeWebToolsMock, runtimePrepareImportMock } = vi.hoisted(() => ({
-  resolveRuntimeWebToolsMock: vi.fn(async () => ({
-    metadata: {
-      search: { providerSource: "none", diagnostics: [] },
-      fetch: { providerSource: "none", diagnostics: [] },
-      diagnostics: [],
-    },
-    degradedOwners: [],
-    secretOwners: [],
-  })),
-  runtimePrepareImportMock: vi.fn(),
-}));
+const { collectConfigAssignmentsMock, resolveRuntimeWebToolsMock, runtimePrepareImportMock } =
+  vi.hoisted(() => ({
+    collectConfigAssignmentsMock:
+      vi.fn<typeof import("./runtime-config-collectors.js").collectConfigAssignments>(),
+    resolveRuntimeWebToolsMock: vi.fn<
+      typeof import("./runtime-web-tools.js").resolveRuntimeWebTools
+    >(async () => ({
+      metadata: {
+        search: { providerSource: "none", diagnostics: [] },
+        fetch: { providerSource: "none", diagnostics: [] },
+        diagnostics: [],
+      },
+      degradedOwners: [],
+      secretOwners: [],
+    })),
+    runtimePrepareImportMock: vi.fn(),
+  }));
 
 function explicitMainRoster() {
   return { agents: { list: [{ id: "main" }] } };
@@ -33,15 +38,24 @@ function explicitMainRoster() {
 vi.mock("./runtime-prepare.runtime.js", () => {
   runtimePrepareImportMock();
   return {
-    createResolverContext: ({ sourceConfig, env }: { sourceConfig: unknown; env: unknown }) => ({
+    createResolverContext: ({
+      sourceConfig,
+      env,
+      manifestRegistry,
+    }: {
+      sourceConfig: unknown;
+      env: unknown;
+      manifestRegistry?: unknown;
+    }) => ({
       sourceConfig,
       env,
       cache: {},
+      ...(manifestRegistry ? { manifestRegistry } : {}),
       warnings: [],
       warningKeys: new Set<string>(),
       assignments: [],
     }),
-    collectConfigAssignments: () => undefined,
+    collectConfigAssignments: collectConfigAssignmentsMock,
     collectAuthStoreAssignments: () => undefined,
     resolveRuntimeWebTools: resolveRuntimeWebToolsMock,
   };
@@ -89,6 +103,7 @@ function writeAuthProfileStore(agentDir: string): void {
 
 describe("secrets runtime fast path", () => {
   afterEach(() => {
+    collectConfigAssignmentsMock.mockReset();
     runtimePrepareImportMock.mockClear();
     resolveRuntimeWebToolsMock.mockClear();
     setActivePluginRegistry(createEmptyPluginRegistry());
@@ -224,6 +239,67 @@ describe("secrets runtime fast path", () => {
     expect(resolveRuntimeWebToolsMock).toHaveBeenCalledTimes(1);
   });
 
+  it("reuses published plugin metadata without reopening manifests for configured web search", async () => {
+    const { prepareSecretsRuntimeSnapshot } = await import("./runtime.js");
+    const { collectConfigAssignments } = await import("./runtime-config-collectors.js");
+    const { resolveRuntimeWebTools } = await import("./runtime-web-tools.js");
+    const { loadPluginMetadataSnapshot } = await import("../plugins/plugin-metadata-snapshot.js");
+    const { setCurrentPluginMetadataSnapshot } =
+      await import("../plugins/current-plugin-metadata-snapshot.js");
+    const { listAgentWorkspaceDirs } = await import("../agents/workspace-dirs.js");
+    const config = asConfig({
+      ...explicitMainRoster(),
+      tools: { web: { search: { provider: "webiq" } } },
+      plugins: {
+        enabled: true,
+        allow: ["workiq-code-mode", "tools-code-mode", "webiq", "diagnostics-otel", "brave"],
+        entries: {
+          "workiq-code-mode": { config: { enabledNamespaces: ["m365", "search"] } },
+          "tools-code-mode": { enabled: true },
+          webiq: { enabled: true, config: { webSearch: { omitAuth: true, region: "US" } } },
+          "diagnostics-otel": { enabled: true },
+        },
+      },
+    });
+    const workspaceDir = listAgentWorkspaceDirs(config, process.env)[0];
+    const pluginMetadataSnapshot = loadPluginMetadataSnapshot({
+      config,
+      env: process.env,
+      workspaceDir,
+    });
+    expect(pluginMetadataSnapshot.plugins.length).toBeGreaterThan(0);
+    setCurrentPluginMetadataSnapshot(pluginMetadataSnapshot, {
+      config,
+      env: process.env,
+      workspaceDir,
+    });
+    collectConfigAssignmentsMock.mockImplementationOnce(collectConfigAssignments);
+    resolveRuntimeWebToolsMock.mockImplementationOnce(resolveRuntimeWebTools);
+    const openSyncSpy = vi.spyOn(fs, "openSync");
+    const probeDescriptor = fs.openSync(pluginMetadataSnapshot.plugins[0]!.manifestPath, "r");
+    fs.closeSync(probeDescriptor);
+    expect(openSyncSpy).toHaveBeenCalledOnce();
+    openSyncSpy.mockClear();
+
+    try {
+      const snapshot = await prepareSecretsRuntimeSnapshot({
+        config,
+        env: process.env,
+        agentDirs: ["/tmp/openclaw-agent-main"],
+        loadAuthStore: emptyAuthStore,
+      });
+
+      const manifestOpens = openSyncSpy.mock.calls.filter(
+        ([filePath]) => typeof filePath === "string" && filePath.endsWith("/openclaw.plugin.json"),
+      );
+      expect(snapshot.webTools.search.diagnostics).toEqual(expect.any(Array));
+      expect(manifestOpens).toHaveLength(0);
+    } finally {
+      openSyncSpy.mockRestore();
+      setCurrentPluginMetadataSnapshot(undefined);
+    }
+  });
+
   it("skips the startup-only fast path when the inherited main auth store exists", async () => {
     const { prepareSecretsRuntimeFastPathSnapshot } = await import("./runtime-fast-path.js");
     const root = mkdtempSync(path.join(tmpdir(), "openclaw-runtime-fast-path-"));

From 7d70895ba3ce2ae5dc34e31f74c8d73501e0f7b4 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 10:59:07 -0700
Subject: [PATCH 049/124] perf(ui): skip video pacing during normal browser
 tests (#127313)

---
 ui/src/e2e/device-scope-upgrade.e2e.test.ts | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/ui/src/e2e/device-scope-upgrade.e2e.test.ts b/ui/src/e2e/device-scope-upgrade.e2e.test.ts
index a67abab1ab37..fb3d63e1c5be 100644
--- a/ui/src/e2e/device-scope-upgrade.e2e.test.ts
+++ b/ui/src/e2e/device-scope-upgrade.e2e.test.ts
@@ -68,6 +68,12 @@ async function captureProof(page: Page, name: string): Promise<void> {
   await page.screenshot({ fullPage: true, path: path.join(proofDir, name) });
 }
 
+async function holdProof(page: Page, durationMs = 500): Promise<void> {
+  if (proofDir) {
+    await page.waitForTimeout(durationMs);
+  }
+}
+
 async function createContext(): Promise<BrowserContext> {
   const context = await browser.newContext({
     locale: "en-US",
@@ -189,13 +195,13 @@ describeControlUiE2e("Control UI live device scope upgrade", () => {
       expect(await mobile.page.locator(".sidebar-update-card--floating").count()).toBe(0);
       expect(await mobile.page.locator(".chat-header-session-menu__status-dot").count()).toBe(1);
       await captureProof(mobile.page, "mobile-compact-header.png");
-      await mobile.page.waitForTimeout(500);
+      await holdProof(mobile.page);
       await menu.click();
       const status = mobile.page.getByText("Limited access", { exact: true });
       await status.waitFor();
       await mobile.page.getByText("Update available v2.0.0", { exact: true }).waitFor();
       await captureProof(mobile.page, "mobile-status-menu.png");
-      await mobile.page.waitForTimeout(500);
+      await holdProof(mobile.page);
       await status.click();
       await mobile.page.getByText("This browser has limited access.", { exact: true }).waitFor();
       await mobile.page
@@ -203,10 +209,10 @@ describeControlUiE2e("Control UI live device scope upgrade", () => {
         .first()
         .waitFor({ state: "hidden" });
       await captureProof(mobile.page, "mobile-access-details.png");
-      await mobile.page.waitForTimeout(700);
+      await holdProof(mobile.page, 700);
       await mobile.page.getByRole("button", { name: "Collapse limited access banner" }).click();
       await menu.waitFor();
-      await mobile.page.waitForTimeout(500);
+      await holdProof(mobile.page);
     } finally {
       await closeProofContext(mobile, "mobile-compact-header");
     }
@@ -219,10 +225,10 @@ describeControlUiE2e("Control UI live device scope upgrade", () => {
       await desktop.page.locator(".shell-chrome-controls__search").first().waitFor();
       await desktop.page.locator(".chat-side-panel-toggle").first().waitFor();
       await captureProof(desktop.page, "desktop-unchanged.png");
-      await desktop.page.waitForTimeout(500);
+      await holdProof(desktop.page);
       await desktop.page.getByRole("button", { name: "Collapse limited access banner" }).click();
       await desktop.page.getByRole("button", { name: "Show limited access details" }).waitFor();
-      await desktop.page.waitForTimeout(500);
+      await holdProof(desktop.page);
     } finally {
       await closeProofContext(desktop, "desktop-unchanged");
     }

From 797d251c68940ba0d70df29fc1522034482827df Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 10:59:25 -0700
Subject: [PATCH 050/124] perf(cron): reuse resolved schedule timezone
 (#127311)

Co-authored-by: Amp <amp@ampcode.com>
---
 src/cron/schedule.ts | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/src/cron/schedule.ts b/src/cron/schedule.ts
index 47cb4e9711d0..c79abfc3d4dd 100644
--- a/src/cron/schedule.ts
+++ b/src/cron/schedule.ts
@@ -37,7 +37,7 @@ function resolveCachedCron(expr: string, timezone: string): Cron {
   return next;
 }
 
-function resolveCronFromSchedule(schedule: { tz?: string; expr?: unknown }): Cron | undefined {
+function resolveCronFromSchedule(schedule: { tz?: string; expr?: unknown }) {
   if (typeof schedule.expr !== "string") {
     throw new Error("invalid cron schedule: expr is required");
   }
@@ -45,7 +45,8 @@ function resolveCronFromSchedule(schedule: { tz?: string; expr?: unknown }): Cro
   if (!expr) {
     return undefined;
   }
-  return resolveCachedCron(expr, resolveCronTimezone(schedule.tz));
+  const timezone = resolveCronTimezone(schedule.tz);
+  return { cron: resolveCachedCron(expr, timezone), timezone };
 }
 
 function hasNearbyCronTimezoneTransition(
@@ -249,16 +250,16 @@ export function computeNextRunAtMs(schedule: CronSchedule, nowMs: number): numbe
     return undefined;
   }
 
-  const cron = resolveCronFromSchedule(schedule);
-  if (!cron) {
+  const resolvedCron = resolveCronFromSchedule(schedule);
+  if (!resolvedCron) {
     return undefined;
   }
+  const { cron, timezone } = resolvedCron;
   const nextMs = cron.nextRun(new Date(nowMs))?.getTime();
   if (nextMs === undefined) {
     return undefined;
   }
 
-  const timezone = resolveCronTimezone(schedule.tz);
   const normalizedNextMs = resolveValidatedNextCronOccurrenceMs(cron, nowMs, nextMs, timezone);
   if (normalizedNextMs !== undefined) {
     return normalizedNextMs;
@@ -292,12 +293,12 @@ export function computePreviousRunAtMs(schedule: CronSchedule, nowMs: number): n
   if (schedule.kind !== "cron" || asDateTimestampMs(nowMs) === undefined) {
     return undefined;
   }
-  const cron = resolveCronFromSchedule(schedule);
-  if (!cron) {
+  const resolvedCron = resolveCronFromSchedule(schedule);
+  if (!resolvedCron) {
     return undefined;
   }
+  const { cron, timezone } = resolvedCron;
   let previousMs = cron.previousRuns(1, new Date(nowMs))[0]?.getTime();
-  const timezone = resolveCronTimezone(schedule.tz);
   if (
     previousMs !== undefined &&
     previousMs < nowMs &&

From c6d6706d8e4f14a2a770ac917166db72a7e7f1e5 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 11:00:40 -0700
Subject: [PATCH 051/124] perf(agents): reuse gateway plugin generation for
 prepared model runtime (#126630)

* perf(agents): reuse gateway plugin generation for prepared model runtime

The model-runtime sidecar rebuilt two broad plugin registries on gateway
startup: 167 imports across 84 plugins (83 loaded twice) with 82 forced
TypeScript transformations, ~39.6s of a ~50s source-checkout startup.

- Reuse the active gateway registry for inbound dispatch when the
  gateway-bindable subagent mode, workspace, and manifest identity of the
  requesting snapshot generation all match; fall back to isolated loading
  otherwise.
- Seed the runtime registry from the inbound registry's plugin ids instead
  of a second unscoped broad load.
- Prefer built plugin artifacts on the agents lane, matching the gateway
  loader; externally-packaged plugins no longer force source transforms.

Measured (M3 Ultra, dist build, median of 3): sidecars.model-runtime
33.93s -> 0.379s; gateway readiness 41.69s -> 7.58s; plugin imports
167 -> 18; TypeScript transformations 82 -> 0.

* fix(agents): keep source artifacts on isolated agent registry loads

The full agents lane caught ~20 Code Mode regressions from preferring
built artifacts on the agents loader lane: in a source checkout a stale
dist silently replaces edited plugin source. The gateway-generation
reuse already removes the broad re-imports that made source transforms
expensive, so the artifact preference is unnecessary for the startup
win and unsafe for dev checkouts.

* fix(agents): bind gateway registry reuse to the current metadata generation

Reuse authority is identity-based: the requesting snapshot must be the
process-current published generation. Bundled manifest records compare by
id+origin only, so an equivalence check alone could let an older or leaked
active registry serve a different generation's plugins.

* perf(agents): resolve prepared-runtime metadata through the current generation

The sidecar acquired its snapshot with loadPluginMetadataSnapshot, which
always constructs a fresh object, so the generation-identity reuse guard
could never hold in the gateway and inbound loads stayed isolated. Resolve
through the slot-probing entry instead; the published current generation
satisfies the read and registry reuse engages.

Test updates: model the current-generation identity in the reuse fixture,
drop stale preferBuiltPluginArtifacts expectations from the isolated-load
fixtures, and add a negative case proving a non-current generation refuses
reuse.

* perf(agents): inherit gateway artifact preference when extending its generation

The runtime-registry delta load re-imported teams-meetings and zoom-meetings
channel graphs through forced source transforms (~9.2s) even though the
reused gateway generation had already realized them from built artifacts.
When the inbound registry is the active gateway registry, the delta load now
inherits the generation owner's built-artifact preference; isolated loads
keep source truth, so source-executed tests and dev flows are unaffected.

Measured (M3 Ultra, dist build, 3 runs): sidecars.model-runtime
289-331ms (baseline 33,930ms); gateway ready 3.7-4.0s (baseline 41.7s);
forced source transforms 0 (baseline 82).

* test(agents): count both slot-probing metadata resolutions in static startup

The prepared cold plugin context now resolves through the canonical
slot-probing entry, joining the model-id normalization lane's existing
resolution. Both share the published generation; the eager-work
protections remain the catalog laziness assertions.

* refactor(agents): compose generation reuse with lifecycle artifact selection

Rebase over #125957, which preserves built-artifact mode for
lifecycle-selected prepared registries. Reuse of the active gateway
generation and the generation-inherited delta preference compose with
that owner's parameter instead of duplicating the forwarding.
---
 ...prepared-model-runtime.inbound-registry.ts |  66 ++++++++--
 ...pared-model-runtime.plugin-context.test.ts |   6 +-
 .../prepared-model-runtime.plugin-context.ts  |  11 +-
 ...pared-model-runtime.startup-static.test.ts |   5 +-
 src/agents/runtime-plugins.test.ts            | 123 ++++++++++++++++++
 5 files changed, 197 insertions(+), 14 deletions(-)

diff --git a/src/agents/prepared-model-runtime.inbound-registry.ts b/src/agents/prepared-model-runtime.inbound-registry.ts
index 8c602b0bc220..de27cd758de7 100644
--- a/src/agents/prepared-model-runtime.inbound-registry.ts
+++ b/src/agents/prepared-model-runtime.inbound-registry.ts
@@ -1,6 +1,16 @@
 import { hashRuntimeConfigValue } from "../config/runtime-snapshot.js";
+import {
+  listRuntimePluginIdsFromRegistry,
+  registryMatchesManifestPluginIds,
+} from "../plugins/active-runtime-registry.js";
+import { getCurrentPluginMetadataSnapshot } from "../plugins/current-plugin-metadata-snapshot.js";
 import type { PluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.types.js";
 import type { PluginRegistry } from "../plugins/registry-types.js";
+import {
+  getActivePluginRegistry,
+  getActivePluginRegistryWorkspaceDir,
+  getActivePluginRuntimeSubagentMode,
+} from "../plugins/runtime.js";
 import type { PreparedModelRuntimeInput } from "./prepared-model-runtime.types.js";
 import { loadAgentRuntimePluginRegistryHandle } from "./runtime-plugins.js";
 
@@ -45,14 +55,41 @@ export function createPreparedInboundRegistryLoader(): PreparedInboundRegistryLo
     if (existing) {
       return existing;
     }
-    const registry = loadAgentRuntimePluginRegistryHandle({
+    const activeRegistry = getActivePluginRegistry();
+    const activeWorkspaceDir = getActivePluginRegistryWorkspaceDir();
+    // Reuse is generation-bound: the requesting snapshot must BE the process-current
+    // published generation, or a leaked/older active registry could satisfy the
+    // manifest match (bundled records compare by id+origin only) and serve another
+    // generation's plugins. Identity, not equivalence, is the authority check here.
+    const currentGenerationSnapshot = getCurrentPluginMetadataSnapshot({
       config: input.config,
-      env: input.env ?? process.env,
-      ...(input.workspaceDir ? { workspaceDir: input.workspaceDir } : {}),
-      ...(input.allowGatewaySubagentBinding ? { allowGatewaySubagentBinding: true } : {}),
-      metadataSnapshot,
-      preferBuiltPluginArtifacts: true,
+      workspaceDir: metadataSnapshot.workspaceDir,
+      allowWorkspaceScopedSnapshot: true,
     });
+    const reusableGatewayRegistry =
+      input.allowGatewaySubagentBinding === true &&
+      input.env === undefined &&
+      getActivePluginRuntimeSubagentMode() === "gateway-bindable" &&
+      activeRegistry &&
+      currentGenerationSnapshot === metadataSnapshot &&
+      (activeWorkspaceDir === undefined || activeWorkspaceDir === metadataSnapshot.workspaceDir) &&
+      registryMatchesManifestPluginIds(
+        activeRegistry,
+        metadataSnapshot.manifestRegistry.plugins,
+        listRuntimePluginIdsFromRegistry(activeRegistry),
+      )
+        ? activeRegistry
+        : undefined;
+    const registry =
+      reusableGatewayRegistry ??
+      loadAgentRuntimePluginRegistryHandle({
+        config: input.config,
+        env: input.env ?? process.env,
+        ...(input.workspaceDir ? { workspaceDir: input.workspaceDir } : {}),
+        ...(input.allowGatewaySubagentBinding ? { allowGatewaySubagentBinding: true } : {}),
+        metadataSnapshot,
+        preferBuiltPluginArtifacts: true,
+      });
     registries.set(key, registry);
     return registry;
   };
@@ -76,16 +113,29 @@ export function prepareWorkspacePluginRegistries(
   const inboundPluginRegistry = input.readOnly
     ? undefined
     : loadInboundRegistry?.(input, metadataSnapshot);
+  // Extending the reused Gateway generation inherits its artifact preference: the
+  // Gateway loader realizes built artifacts, so the delta load must not re-import
+  // the same plugins through source transforms. Isolated loads keep source truth.
+  const extendsActiveGatewayGeneration =
+    inboundPluginRegistry !== undefined && inboundPluginRegistry === getActivePluginRegistry();
   const runtimePluginRegistry =
     input.runtimePluginSelections || !inboundPluginRegistry
       ? loadAgentRuntimePluginRegistryHandle({
-          ...(input.loadRuntimePlugins ? { basePluginIds: [] } : {}),
+          ...(input.loadRuntimePlugins
+            ? { basePluginIds: [] }
+            : inboundPluginRegistry
+              ? { basePluginIds: listRuntimePluginIdsFromRegistry(inboundPluginRegistry) }
+              : {}),
           config: input.config,
           env: input.env ?? process.env,
           ...(input.workspaceDir ? { workspaceDir: input.workspaceDir } : {}),
           ...(input.allowGatewaySubagentBinding ? { allowGatewaySubagentBinding: true } : {}),
           metadataSnapshot,
-          ...(preferBuiltPluginArtifacts ? { preferBuiltPluginArtifacts: true } : {}),
+          // Lifecycle-selected callers and delta loads extending the active Gateway
+          // generation both stay on built artifacts; isolated loads keep source truth.
+          ...(preferBuiltPluginArtifacts || extendsActiveGatewayGeneration
+            ? { preferBuiltPluginArtifacts: true }
+            : {}),
           selections: input.runtimePluginSelections,
         })
       : inboundPluginRegistry;
diff --git a/src/agents/prepared-model-runtime.plugin-context.test.ts b/src/agents/prepared-model-runtime.plugin-context.test.ts
index 1570f26955e5..0fda939928cf 100644
--- a/src/agents/prepared-model-runtime.plugin-context.test.ts
+++ b/src/agents/prepared-model-runtime.plugin-context.test.ts
@@ -70,7 +70,7 @@ describe("prepared model runtime plugin metadata ownership", () => {
       workspaceDir,
     });
     const resolveMetadata = vi
-      .spyOn(pluginMetadata, "loadPluginMetadataSnapshot")
+      .spyOn(pluginMetadata, "resolvePluginMetadataSnapshot")
       .mockReturnValue(directSnapshot);
     const registry = createEmptyPluginRegistry();
 
@@ -94,6 +94,7 @@ describe("prepared model runtime plugin metadata ownership", () => {
         config,
         env: process.env,
         workspaceDir,
+        allowWorkspaceScopedCurrent: true,
       });
     } finally {
       resolveMetadata.mockRestore();
@@ -109,7 +110,7 @@ describe("prepared model runtime plugin metadata ownership", () => {
       workspaceDir,
     });
     const resolveMetadata = vi
-      .spyOn(pluginMetadata, "loadPluginMetadataSnapshot")
+      .spyOn(pluginMetadata, "resolvePluginMetadataSnapshot")
       .mockReturnValue(directSnapshot);
 
     try {
@@ -129,6 +130,7 @@ describe("prepared model runtime plugin metadata ownership", () => {
         config,
         env: process.env,
         workspaceDir,
+        allowWorkspaceScopedCurrent: true,
         pluginIdScope: expect.objectContaining({ key: expect.any(String) }),
       });
     } finally {
diff --git a/src/agents/prepared-model-runtime.plugin-context.ts b/src/agents/prepared-model-runtime.plugin-context.ts
index 5af021c1ae89..dc197cbfc7df 100644
--- a/src/agents/prepared-model-runtime.plugin-context.ts
+++ b/src/agents/prepared-model-runtime.plugin-context.ts
@@ -1,6 +1,6 @@
 import type { PluginDiscoveryResult } from "../plugins/discovery.js";
 import { extractPluginInstallRecordsFromInstalledPluginIndex } from "../plugins/installed-plugin-index-install-records.js";
-import { loadPluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js";
+import { resolvePluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js";
 import type { PluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.types.js";
 import type { PluginRegistry } from "../plugins/registry-types.js";
 import {
@@ -74,10 +74,15 @@ function resolveColdMetadataSnapshot(
   input: PreparedModelRuntimeInput,
   env: NodeJS.ProcessEnv,
 ): PluginMetadataSnapshot {
-  const resolvedMetadataSnapshot = loadPluginMetadataSnapshot({
+  // Resolve (slot-probing) instead of load: in the gateway the published current
+  // generation satisfies this read, which keeps snapshot identity stable for the
+  // generation-bound registry reuse in the inbound loader.
+  const resolvedMetadataSnapshot = resolvePluginMetadataSnapshot({
     config: input.config,
     env,
-    ...(input.workspaceDir ? { workspaceDir: input.workspaceDir } : {}),
+    ...(input.workspaceDir
+      ? { workspaceDir: input.workspaceDir, allowWorkspaceScopedCurrent: true }
+      : {}),
     ...(input.loadRuntimePlugins && input.runtimePluginSelections && input.workspaceDir
       ? {
           pluginIdScope: createAgentRuntimeMetadataPluginIdScope({
diff --git a/src/agents/prepared-model-runtime.startup-static.test.ts b/src/agents/prepared-model-runtime.startup-static.test.ts
index a988bbbb85e1..5d26256dfaaf 100644
--- a/src/agents/prepared-model-runtime.startup-static.test.ts
+++ b/src/agents/prepared-model-runtime.startup-static.test.ts
@@ -407,7 +407,10 @@ describe("prepared model runtime Gateway catalog mode", () => {
     );
     expect(mocks.buildPreparedModelCatalogSnapshot).not.toHaveBeenCalled();
     expect(mocks.loadStaticCatalog).not.toHaveBeenCalled();
-    expect(mocks.resolvePluginMetadataSnapshot).toHaveBeenCalledOnce();
+    // Two slot-probing resolutions share the published generation: the prepared
+    // cold plugin context and the model-id normalization lane. Neither builds a
+    // catalog; the laziness guards above are the eager-work protections.
+    expect(mocks.resolvePluginMetadataSnapshot).toHaveBeenCalledTimes(2);
     expect(configuredRuntimeModelCount).toBe(1);
     expect(generatedCatalogReadCount).toBe(0);
     const snapshot = getPreparedModelRuntimeSnapshot({
diff --git a/src/agents/runtime-plugins.test.ts b/src/agents/runtime-plugins.test.ts
index 9ff17434dc04..262abc227b33 100644
--- a/src/agents/runtime-plugins.test.ts
+++ b/src/agents/runtime-plugins.test.ts
@@ -3,7 +3,10 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const hoisted = vi.hoisted(() => ({
   loadPluginMetadataSnapshot: vi.fn(),
+  getCurrentPluginMetadataSnapshot: vi.fn(),
   getActivePluginRegistry: vi.fn(),
+  getActivePluginRegistryWorkspaceDir: vi.fn(),
+  getActivePluginRuntimeSubagentMode: vi.fn(),
   loadPluginRegistryHandle: vi.fn(),
   adoptRuntimeContextEngineRegistrations: vi.fn((target: unknown) => target),
   adoptRuntimeWidgetPresenterRegistrations: vi.fn((target: unknown) => target),
@@ -19,6 +22,8 @@ vi.mock("../context-engine/registry.js", () => ({
 
 vi.mock("../plugins/runtime.js", () => ({
   getActivePluginRegistry: hoisted.getActivePluginRegistry,
+  getActivePluginRegistryWorkspaceDir: hoisted.getActivePluginRegistryWorkspaceDir,
+  getActivePluginRuntimeSubagentMode: hoisted.getActivePluginRuntimeSubagentMode,
 }));
 
 vi.mock("../plugins/widget-presenters.js", () => ({
@@ -29,6 +34,10 @@ vi.mock("../plugins/plugin-metadata-snapshot.js", () => ({
   loadPluginMetadataSnapshot: hoisted.loadPluginMetadataSnapshot,
 }));
 
+vi.mock("../plugins/current-plugin-metadata-snapshot.js", () => ({
+  getCurrentPluginMetadataSnapshot: hoisted.getCurrentPluginMetadataSnapshot,
+}));
+
 vi.mock("../plugins/loader.js", () => ({
   loadPluginRegistryHandle: hoisted.loadPluginRegistryHandle,
 }));
@@ -42,6 +51,10 @@ import {
   getPluginRuntimeGatewayRequestScope,
   withPluginRuntimeRegistryScope,
 } from "../plugins/runtime/gateway-request-scope.js";
+import {
+  createPreparedInboundRegistryLoader,
+  prepareWorkspacePluginRegistries,
+} from "./prepared-model-runtime.inbound-registry.js";
 import {
   loadAgentRuntimePluginRegistryHandle,
   withAgentPluginRegistry,
@@ -68,7 +81,10 @@ describe("agent runtime plugin registries", () => {
         ...createMetadataSnapshot(params.workspaceDir),
         pluginIds: undefined,
       }));
+    hoisted.getCurrentPluginMetadataSnapshot.mockReset().mockReturnValue(undefined);
     hoisted.getActivePluginRegistry.mockReset().mockReturnValue(undefined);
+    hoisted.getActivePluginRegistryWorkspaceDir.mockReset().mockReturnValue(undefined);
+    hoisted.getActivePluginRuntimeSubagentMode.mockReset().mockReturnValue("default");
     hoisted.loadPluginRegistryHandle.mockReset().mockReturnValue({ handle: true });
     hoisted.adoptRuntimeContextEngineRegistrations
       .mockReset()
@@ -106,6 +122,113 @@ describe("agent runtime plugin registries", () => {
     );
   });
 
+  it("reuses the Gateway inbound registry and loads only its selected provider delta", () => {
+    const config = {} as never;
+    const gatewayPlugin = {
+      id: "gateway-owned",
+      origin: "bundled",
+      rootDir: "/dist/extensions/gateway-owned",
+      source: "/dist/extensions/gateway-owned/index.js",
+      status: "loaded",
+    };
+    const activeRegistry = { plugins: [gatewayPlugin] };
+    const selectedRegistry = { plugins: [gatewayPlugin, { id: "selected-provider" }] };
+    const metadataSnapshot = {
+      ...createMetadataSnapshot("/tmp/default-workspace", undefined),
+      manifestRegistry: {
+        diagnostics: [],
+        plugins: [
+          {
+            id: "gateway-owned",
+            origin: "bundled",
+            rootDir: "/extensions/gateway-owned",
+            source: "/extensions/gateway-owned/index.ts",
+          },
+        ],
+      },
+    };
+    hoisted.getActivePluginRegistry.mockReturnValue(activeRegistry);
+    hoisted.getActivePluginRuntimeSubagentMode.mockReturnValue("gateway-bindable");
+    hoisted.getCurrentPluginMetadataSnapshot.mockImplementation(() => metadataSnapshot);
+    hoisted.loadPluginRegistryHandle.mockReturnValue(selectedRegistry);
+    hoisted.resolveAgentRuntimePluginLoadPlan.mockImplementation(({ basePluginIds }) => ({
+      config,
+      pluginIds: [...(basePluginIds ?? []), "selected-provider"],
+    }));
+
+    const prepared = prepareWorkspacePluginRegistries(
+      {
+        agentDir: "/tmp/agent",
+        allowGatewaySubagentBinding: true,
+        config,
+        runtimePluginSelections: [{ provider: "selected", modelId: "model" }],
+        workspaceDir: "/tmp/default-workspace",
+      },
+      metadataSnapshot as never,
+      createPreparedInboundRegistryLoader(),
+    );
+
+    expect(prepared.inboundPluginRegistry).toBe(activeRegistry);
+    expect(prepared.runtimePluginRegistry).toBe(selectedRegistry);
+    expect(hoisted.loadPluginRegistryHandle).toHaveBeenCalledOnce();
+    expect(hoisted.loadPluginRegistryHandle).toHaveBeenCalledWith(
+      expect.objectContaining({
+        onlyPluginIds: ["gateway-owned", "selected-provider"],
+      }),
+    );
+  });
+
+  it("refuses Gateway registry reuse for a non-current metadata generation", () => {
+    const config = {} as never;
+    const gatewayPlugin = {
+      id: "gateway-owned",
+      origin: "bundled",
+      rootDir: "/dist/extensions/gateway-owned",
+      source: "/dist/extensions/gateway-owned/index.js",
+      status: "loaded",
+    };
+    const activeRegistry = { plugins: [gatewayPlugin] };
+    const metadataSnapshot = {
+      ...createMetadataSnapshot("/tmp/default-workspace", undefined),
+      manifestRegistry: {
+        diagnostics: [],
+        plugins: [
+          {
+            id: "gateway-owned",
+            origin: "bundled",
+            rootDir: "/extensions/gateway-owned",
+            source: "/extensions/gateway-owned/index.ts",
+          },
+        ],
+      },
+    };
+    hoisted.getActivePluginRegistry.mockReturnValue(activeRegistry);
+    hoisted.getActivePluginRuntimeSubagentMode.mockReturnValue("gateway-bindable");
+    // A different (older/leaked) generation is current: identity must fail closed.
+    hoisted.getCurrentPluginMetadataSnapshot.mockReturnValue(
+      createMetadataSnapshot("/tmp/default-workspace", undefined),
+    );
+    hoisted.loadPluginRegistryHandle.mockReturnValue({ plugins: [] });
+    hoisted.resolveAgentRuntimePluginLoadPlan.mockImplementation(({ basePluginIds }) => ({
+      config,
+      pluginIds: basePluginIds,
+    }));
+
+    const loadInboundRegistry = createPreparedInboundRegistryLoader();
+    const inbound = loadInboundRegistry(
+      {
+        agentDir: "/tmp/agent",
+        allowGatewaySubagentBinding: true,
+        config,
+        workspaceDir: "/tmp/default-workspace",
+      },
+      metadataSnapshot as never,
+    );
+
+    expect(inbound).not.toBe(activeRegistry);
+    expect(hoisted.loadPluginRegistryHandle).toHaveBeenCalled();
+  });
+
   it("keeps direct no-current loads on the requested workspace", () => {
     const config = {} as never;
     const env = { OPENCLAW_STATE_DIR: "/tmp/openclaw-state" };

From 2bd6efb919d0685922af7012dab194382fa981ff Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 11:13:21 -0700
Subject: [PATCH 052/124] fix(ui): restore editable map-valued settings
 (#127336)

---
 .../config-form-map-integrity.browser.test.ts | 71 ++++++++++++++++++-
 ui/src/components/config-form.analyze.ts      | 13 +++-
 ui/src/lib/config-form-utils.ts               |  1 +
 3 files changed, 83 insertions(+), 2 deletions(-)

diff --git a/ui/src/components/config-form-map-integrity.browser.test.ts b/ui/src/components/config-form-map-integrity.browser.test.ts
index fc09b462ec25..042178db9702 100644
--- a/ui/src/components/config-form-map-integrity.browser.test.ts
+++ b/ui/src/components/config-form-map-integrity.browser.test.ts
@@ -1,5 +1,5 @@
 import { render } from "lit";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { ConfigFormCollectionDraft } from "./config-form-collection-draft.ts";
 import { analyzeConfigSchema, renderConfigForm } from "./config-form.ts";
 
@@ -12,6 +12,75 @@ function expectElement<T extends Element>(element: T | null | undefined, label:
 }
 
 describe("config form map integrity", () => {
+  it("keeps plain-string record keys editable through nested maps", () => {
+    const analysis = analyzeConfigSchema({
+      type: "object",
+      properties: {
+        values: {
+          type: "object",
+          propertyNames: { type: "string" },
+          additionalProperties: {
+            type: "object",
+            propertyNames: { type: "string" },
+            additionalProperties: { type: "string" },
+          },
+        },
+      },
+    });
+
+    expect(analysis.unsupportedPaths).toEqual([]);
+
+    const container = document.createElement("div");
+    const onPatch = vi.fn();
+    render(
+      renderConfigForm({
+        schema: analysis.schema,
+        uiHints: {},
+        unsupportedPaths: analysis.unsupportedPaths,
+        value: { values: { primary: { region: "west" } } },
+        showAdvanced: true,
+        onShowAdvanced: () => {},
+        onPatch,
+      }),
+      container,
+    );
+
+    expect(container.querySelectorAll(".cfg-map")).toHaveLength(2);
+    expect(container.textContent).not.toContain("Unsupported schema node");
+
+    const nestedKey = expectElement(
+      container.querySelector<HTMLInputElement>('[aria-label="Key: region"]'),
+      "nested map key",
+    );
+    nestedKey.value = "zone";
+    nestedKey.dispatchEvent(new Event("change", { bubbles: true }));
+    expect(onPatch).toHaveBeenCalledWith(["values", "primary"], { zone: "west" });
+  });
+
+  it.each([
+    ["pattern", { type: "string", pattern: "^[a-z]+$" }],
+    ["minimum length", { type: "string", minLength: 1 }],
+    ["enumeration", { enum: ["primary"] }],
+    ["boolean", true],
+    ["null", null],
+    ["array", [{ type: "string" }]],
+    ["wrong type", { type: "number" }],
+    ["inherited type", Object.assign(Object.create({ type: "string" }), { unknown: true })],
+  ])("keeps %s property-name constraints fail-closed", (_label, propertyNames) => {
+    const analysis = analyzeConfigSchema({
+      type: "object",
+      properties: {
+        values: {
+          type: "object",
+          propertyNames,
+          additionalProperties: { type: "string" },
+        },
+      },
+    });
+
+    expect(analysis.unsupportedPaths).toEqual(["values"]);
+  });
+
   it("retains unset map drafts until the collection source changes", async () => {
     const container = document.createElement("div");
     document.body.append(container);
diff --git a/ui/src/components/config-form.analyze.ts b/ui/src/components/config-form.analyze.ts
index b1e51ee8ff90..eadf4543a05d 100644
--- a/ui/src/components/config-form.analyze.ts
+++ b/ui/src/components/config-form.analyze.ts
@@ -146,7 +146,18 @@ function hasOnlySupportedConstraintKeywords(schema: JsonSchema): boolean {
 }
 
 function hasOnlySupportedFormKeywords(schema: JsonSchema): boolean {
-  return Object.keys(schema).every((key) => SUPPORTED_FORM_SCHEMA_KEYS.has(key));
+  return Object.keys(schema).every(
+    (key) =>
+      SUPPORTED_FORM_SCHEMA_KEYS.has(key) ||
+      // JSON object keys are already strings; constrained names must remain fail-closed.
+      (key === "propertyNames" &&
+        typeof schema.propertyNames === "object" &&
+        schema.propertyNames !== null &&
+        !Array.isArray(schema.propertyNames) &&
+        Object.keys(schema.propertyNames).length === 1 &&
+        Object.hasOwn(schema.propertyNames, "type") &&
+        schema.propertyNames.type === "string"),
+  );
 }
 
 function schemaAllowsNull(schema: JsonSchema, seen = new Set<JsonSchema>()): boolean {
diff --git a/ui/src/lib/config-form-utils.ts b/ui/src/lib/config-form-utils.ts
index d08e09b28359..1b9fe047a5f8 100644
--- a/ui/src/lib/config-form-utils.ts
+++ b/ui/src/lib/config-form-utils.ts
@@ -9,6 +9,7 @@ export type JsonSchema = {
   tags?: string[];
   "x-tags"?: string[];
   properties?: Record<string, JsonSchema>;
+  propertyNames?: JsonSchema | boolean;
   required?: string[];
   items?: JsonSchema | JsonSchema[];
   additionalItems?: JsonSchema | boolean;

From 887b9dd5e879c10fac60b22eae4a7ce753884bfa Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 11:13:54 -0700
Subject: [PATCH 053/124] fix(macos): keep Cron run history matched to the
 selected job (#127266)

* fix(macos): own Cron history refreshes

* fix(macos): preserve Gateway recovery across cancellation
---
 .../Sources/OpenClaw/CronJobsStore.swift      | 107 ++--
 .../OpenClaw/CronSettings+Layout.swift        |   7 +-
 .../Sources/OpenClaw/CronSettings+Rows.swift  |   2 +-
 .../Sources/OpenClaw/GatewayConnection.swift  |   1 +
 .../OpenClawIPCTests/CronJobsStoreTests.swift | 565 ++++++++++++++++++
 .../GatewayConnectionControlTests.swift       | 211 +++++++
 6 files changed, 848 insertions(+), 45 deletions(-)
 create mode 100644 apps/macos/Tests/OpenClawIPCTests/CronJobsStoreTests.swift

diff --git a/apps/macos/Sources/OpenClaw/CronJobsStore.swift b/apps/macos/Sources/OpenClaw/CronJobsStore.swift
index f077b955fa2f..fa83cfdffa1a 100644
--- a/apps/macos/Sources/OpenClaw/CronJobsStore.swift
+++ b/apps/macos/Sources/OpenClaw/CronJobsStore.swift
@@ -27,19 +27,24 @@ final class CronJobsStore {
     private var runsTask: Task<Void, Never>?
     private var eventTask: Task<Void, Never>?
     private var pollTask: Task<Void, Never>?
+    private var runsGeneration: UInt64 = 0
 
+    private let gateway: GatewayConnection
     private let interval: TimeInterval = 30
     private let isPreview: Bool
 
-    init(isPreview: Bool = ProcessInfo.processInfo.isPreview) {
+    init(gateway: GatewayConnection = .shared, isPreview: Bool = ProcessInfo.processInfo.isPreview) {
+        self.gateway = gateway
         self.isPreview = isPreview
     }
 
     func start() {
-        guard !self.isPreview else { return }
-        guard self.eventTask == nil else { return }
-        GatewayPushSubscription.restartTask(task: &self.eventTask) { [weak self] push in
-            self?.handle(push: push)
+        guard !self.isPreview, self.eventTask == nil else { return }
+        self.eventTask = Task { [weak self, gateway] in
+            for await push in await gateway.subscribe() {
+                guard !Task.isCancelled, let self else { return }
+                self.handle(push: push)
+            }
         }
         SimpleTaskSupport.startDetachedLoop(task: &self.pollTask, interval: self.interval) { [weak self] in
             await self?.refreshJobs()
@@ -47,14 +52,10 @@ final class CronJobsStore {
     }
 
     func stop() {
-        self.refreshTask?.cancel()
-        self.refreshTask = nil
-        self.runsTask?.cancel()
-        self.runsTask = nil
-        self.eventTask?.cancel()
-        self.eventTask = nil
-        self.pollTask?.cancel()
-        self.pollTask = nil
+        SimpleTaskSupport.stop(task: &self.refreshTask)
+        self.invalidateRuns()
+        SimpleTaskSupport.stop(task: &self.eventTask)
+        SimpleTaskSupport.stop(task: &self.pollTask)
     }
 
     func refreshJobs() async {
@@ -65,12 +66,17 @@ final class CronJobsStore {
         defer { self.isLoadingJobs = false }
 
         do {
-            if let status = try? await GatewayConnection.shared.cronStatus() {
+            if let status = try? await self.gateway.cronStatus() {
                 self.schedulerEnabled = status.enabled
                 self.schedulerStorePath = status.sqlitePath ?? status.storePath
                 self.schedulerNextWakeAtMs = status.nextWakeAtMs
             }
-            self.jobs = try await GatewayConnection.shared.cronList(includeDisabled: true)
+            self.jobs = try await self.gateway.cronList(includeDisabled: true)
+            if let selectedJobId = self.selectedJobId,
+               !self.jobs.contains(where: { $0.id == selectedJobId })
+            {
+                self.clearSelectedJob()
+            }
             if self.jobs.isEmpty {
                 self.statusMessage = "No cron jobs yet."
             }
@@ -80,22 +86,40 @@ final class CronJobsStore {
         }
     }
 
-    func refreshRuns(jobId: String, limit: Int = 200) async {
-        guard !self.isLoadingRuns else { return }
-        self.isLoadingRuns = true
-        defer { self.isLoadingRuns = false }
+    func selectJob(_ id: String) {
+        if self.selectedJobId != id {
+            self.selectedJobId = id
+            self.runEntries = []
+        }
+        self.refreshRuns(jobId: id)
+    }
 
-        do {
-            self.runEntries = try await GatewayConnection.shared.cronRuns(jobId: jobId, limit: limit)
-        } catch {
-            self.logger.error("cron.runs failed \(error.localizedDescription, privacy: .public)")
-            self.lastError = error.localizedDescription
+    func refreshRuns(jobId: String, limit: Int = 200, delay: TimeInterval = 0) {
+        guard self.selectedJobId == jobId else { return }
+        // Claim before scheduling so late completions cannot own a newer selection.
+        self.runsGeneration &+= 1
+        let generation = self.runsGeneration
+        self.isLoadingRuns = true
+        self.lastError = nil
+        SimpleTaskSupport.schedule(task: &self.runsTask, delay: delay) { [weak self] in
+            guard let self, self.ownsRunsRequest(generation, jobId: jobId) else { return }
+            do {
+                let entries = try await self.gateway.cronRuns(jobId: jobId, limit: limit)
+                guard self.ownsRunsRequest(generation, jobId: jobId) else { return }
+                self.runEntries = entries
+            } catch {
+                guard self.ownsRunsRequest(generation, jobId: jobId) else { return }
+                self.logger.error("cron.runs failed \(error.localizedDescription, privacy: .public)")
+                self.lastError = error.localizedDescription
+            }
+            self.isLoadingRuns = false
+            self.runsTask = nil
         }
     }
 
     func runJob(id: String, force: Bool = true) async {
         do {
-            try await GatewayConnection.shared.cronRun(jobId: id, force: force)
+            try await self.gateway.cronRun(jobId: id, force: force)
         } catch {
             self.lastError = error.localizedDescription
         }
@@ -103,12 +127,11 @@ final class CronJobsStore {
 
     func removeJob(id: String) async {
         do {
-            try await GatewayConnection.shared.cronRemove(jobId: id)
-            await self.refreshJobs()
+            try await self.gateway.cronRemove(jobId: id)
             if self.selectedJobId == id {
-                self.selectedJobId = nil
-                self.runEntries = []
+                self.clearSelectedJob()
             }
+            await self.refreshJobs()
         } catch {
             self.lastError = error.localizedDescription
         }
@@ -116,7 +139,7 @@ final class CronJobsStore {
 
     func setJobEnabled(id: String, enabled: Bool) async {
         do {
-            try await GatewayConnection.shared.cronUpdate(
+            try await self.gateway.cronUpdate(
                 jobId: id,
                 patch: ["enabled": AnyCodable(enabled)])
             await self.refreshJobs()
@@ -130,9 +153,9 @@ final class CronJobsStore {
         payload: [String: AnyCodable]) async throws
     {
         if let id {
-            try await GatewayConnection.shared.cronUpdate(jobId: id, patch: payload)
+            try await self.gateway.cronUpdate(jobId: id, patch: payload)
         } else {
-            try await GatewayConnection.shared.cronAdd(payload: payload)
+            try await self.gateway.cronAdd(payload: payload)
         }
         await self.refreshJobs()
     }
@@ -157,7 +180,7 @@ final class CronJobsStore {
         // Keep UI in sync with the gateway scheduler.
         self.scheduleRefresh(delayMs: 250)
         if evt.action == "finished", let selected = self.selectedJobId, selected == evt.jobId {
-            self.scheduleRunsRefresh(jobId: selected, delayMs: 200)
+            self.refreshRuns(jobId: selected, delay: 0.2)
         }
     }
 
@@ -167,11 +190,19 @@ final class CronJobsStore {
         }
     }
 
-    private func scheduleRunsRefresh(jobId: String, delayMs: Int = 200) {
-        SimpleTaskSupport.schedule(task: &self.runsTask, delay: TimeInterval(delayMs) / 1000) { [weak self] in
-            await self?.refreshRuns(jobId: jobId)
-        }
+    private func clearSelectedJob() {
+        self.invalidateRuns()
+        self.selectedJobId = nil
+        self.runEntries = []
     }
 
-    // MARK: - (no additional RPC helpers)
+    private func ownsRunsRequest(_ generation: UInt64, jobId: String) -> Bool {
+        self.runsGeneration == generation && self.selectedJobId == jobId && !Task.isCancelled
+    }
+
+    private func invalidateRuns() {
+        self.runsGeneration &+= 1
+        SimpleTaskSupport.stop(task: &self.runsTask)
+        self.isLoadingRuns = false
+    }
 }
diff --git a/apps/macos/Sources/OpenClaw/CronSettings+Layout.swift b/apps/macos/Sources/OpenClaw/CronSettings+Layout.swift
index e152ad55f8e7..b27742ef36d5 100644
--- a/apps/macos/Sources/OpenClaw/CronSettings+Layout.swift
+++ b/apps/macos/Sources/OpenClaw/CronSettings+Layout.swift
@@ -150,7 +150,7 @@ extension CronSettings {
                     LazyVStack(alignment: .leading, spacing: 4) {
                         ForEach(self.store.jobs) { job in
                             Button {
-                                self.selectJob(job.id)
+                                self.store.selectJob(job.id)
                             } label: {
                                 self.jobRow(job)
                                     .frame(maxWidth: .infinity, alignment: .leading)
@@ -184,11 +184,6 @@ extension CronSettings {
         }
     }
 
-    private func selectJob(_ id: String) {
-        self.store.selectedJobId = id
-        Task { await self.store.refreshRuns(jobId: id) }
-    }
-
     @ViewBuilder
     var detail: some View {
         if let selected = self.selectedJob {
diff --git a/apps/macos/Sources/OpenClaw/CronSettings+Rows.swift b/apps/macos/Sources/OpenClaw/CronSettings+Rows.swift
index 5a3c4188cf4e..bd00c3323201 100644
--- a/apps/macos/Sources/OpenClaw/CronSettings+Rows.swift
+++ b/apps/macos/Sources/OpenClaw/CronSettings+Rows.swift
@@ -149,7 +149,7 @@ extension CronSettings {
                     .font(.headline)
                 Spacer()
                 Button {
-                    Task { await self.store.refreshRuns(jobId: job.id) }
+                    self.store.refreshRuns(jobId: job.id)
                 } label: {
                     Label("Refresh", systemImage: "arrow.clockwise")
                 }
diff --git a/apps/macos/Sources/OpenClaw/GatewayConnection.swift b/apps/macos/Sources/OpenClaw/GatewayConnection.swift
index d148aa0dfa6d..5b8f7a911c58 100644
--- a/apps/macos/Sources/OpenClaw/GatewayConnection.swift
+++ b/apps/macos/Sources/OpenClaw/GatewayConnection.swift
@@ -291,6 +291,7 @@ actor GatewayConnection {
         do {
             return try await client.request(method: method, params: params, timeoutMs: timeoutMs)
         } catch {
+            try Task.checkCancellation()
             if allowTLSRepair,
                let tlsError = error as? GatewayTLSValidationError,
                await GatewayTLSRepairCoordinator.shared.repair(
diff --git a/apps/macos/Tests/OpenClawIPCTests/CronJobsStoreTests.swift b/apps/macos/Tests/OpenClawIPCTests/CronJobsStoreTests.swift
new file mode 100644
index 000000000000..c5f5f13a35d8
--- /dev/null
+++ b/apps/macos/Tests/OpenClawIPCTests/CronJobsStoreTests.swift
@@ -0,0 +1,565 @@
+import Foundation
+import Testing
+@testable import OpenClaw
+@testable import OpenClawKit
+
+private struct CronGatewayRequest: Sendable {
+    let id: String
+    let method: String
+    let jobId: String?
+}
+
+private actor CronGatewayRequestLog {
+    private var requests: [CronGatewayRequest] = []
+    private var endpointLookups = 0
+    private var availableJobs = ["job-a", "job-b"]
+    private var nextEventSequence = 0
+
+    func append(_ request: CronGatewayRequest) {
+        self.requests.append(request)
+    }
+
+    func lookupEndpoint() {
+        self.endpointLookups += 1
+    }
+
+    func endpointLookupCount() -> Int {
+        self.endpointLookups
+    }
+
+    func request(jobId: String, occurrence: Int = 0) -> CronGatewayRequest? {
+        let matches = self.requests.filter { $0.method == "cron.runs" && $0.jobId == jobId }
+        guard matches.indices.contains(occurrence) else { return nil }
+        return matches[occurrence]
+    }
+
+    func requestCount(method: String, jobId: String? = nil) -> Int {
+        self.requests.count { $0.method == method && (jobId == nil || $0.jobId == jobId) }
+    }
+
+    func removeJob(_ jobId: String) {
+        self.availableJobs.removeAll { $0 == jobId }
+    }
+
+    func jobsResponse() -> String {
+        let jobs = self.availableJobs.map { jobId in
+            #"{"id":"\#(jobId)","name":"\#(jobId)","enabled":true,"createdAtMs":0,"updatedAtMs":0,"# +
+                #""schedule":{"kind":"every","everyMs":1000},"sessionTarget":"isolated","wakeMode":"now","# +
+                #""payload":{"kind":"systemEvent","text":"test"},"state":{}}"#
+        }.joined(separator: ",")
+        return #"{"jobs":[\#(jobs)]}"#
+    }
+
+    func eventSequence() -> Int {
+        self.nextEventSequence += 1
+        return self.nextEventSequence
+    }
+}
+
+private final class CronGatewayFixture: @unchecked Sendable {
+    let requests: CronGatewayRequestLog
+    let session: GatewayTestWebSocketSession
+    let gateway: GatewayConnection
+
+    init(recoveryEligible: Bool = false, initialRunsFailure: (any Error & Sendable)? = nil) {
+        let requests = CronGatewayRequestLog()
+        self.requests = requests
+        self.session = GatewayTestWebSocketSession(taskFactory: {
+            GatewayTestWebSocketTask(sendHook: { socket, message, sendIndex in
+                guard sendIndex > 0,
+                      let request = Self.decodeRequest(message)
+                else { return }
+                await requests.append(request)
+                guard request.method != "cron.runs" else {
+                    if let initialRunsFailure,
+                       await requests.requestCount(method: "cron.runs") == 1
+                    {
+                        throw initialRunsFailure
+                    }
+                    return
+                }
+                let payload: String
+                switch request.method {
+                case "cron.status":
+                    payload = #"{"enabled":true,"storePath":"/tmp/cron-tests","jobs":2}"#
+                case "cron.list":
+                    payload = await requests.jobsResponse()
+                case "cron.remove":
+                    if let jobId = request.jobId {
+                        await requests.removeJob(jobId)
+                    }
+                    payload = #"{"ok":true}"#
+                default:
+                    payload = #"{"ok":true}"#
+                }
+                socket.emitReceiveSuccess(.data(Data(
+                    #"{"type":"res","id":"\#(request.id)","ok":true,"payload":\#(payload)}"#.utf8)))
+            })
+        })
+        if recoveryEligible {
+            self.gateway = GatewayConnection(
+                endpointProvider: {
+                    await requests.lookupEndpoint()
+                    return GatewayConnection.EndpointSnapshot(
+                        config: (url: URL(string: "ws://127.0.0.1:1")!, token: nil, password: nil),
+                        routeAuthority: nil)
+                },
+                supportsSharedEndpointRecovery: true,
+                activationBindingKeyProvider: { nil },
+                sessionBox: WebSocketSessionBox(session: self.session))
+        } else {
+            self.gateway = GatewayConnection(
+                configProvider: {
+                    await requests.lookupEndpoint()
+                    return (url: URL(string: "ws://127.0.0.1:1")!, token: nil, password: nil)
+                },
+                sessionBox: WebSocketSessionBox(session: self.session))
+        }
+    }
+
+    private static func decodeRequest(_ message: URLSessionWebSocketTask.Message) -> CronGatewayRequest? {
+        let data: Data? = switch message {
+        case let .data(data): data
+        case let .string(value): value.data(using: .utf8)
+        @unknown default: nil
+        }
+        guard let data,
+              let frame = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+              let id = frame["id"] as? String,
+              let method = frame["method"] as? String
+        else { return nil }
+        let parameters = frame["params"] as? [String: Any]
+        return CronGatewayRequest(id: id, method: method, jobId: parameters?["id"] as? String)
+    }
+
+    func waitForRequest(
+        jobId: String,
+        occurrence: Int = 0,
+        timeout: Duration = .seconds(2)) async -> CronGatewayRequest?
+    {
+        let deadline = ContinuousClock.now + timeout
+        while ContinuousClock.now < deadline {
+            if let request = await self.requests.request(jobId: jobId, occurrence: occurrence) {
+                return request
+            }
+            try? await Task.sleep(for: .milliseconds(2))
+        }
+        return await self.requests.request(jobId: jobId, occurrence: occurrence)
+    }
+
+    func respond(
+        to request: CronGatewayRequest,
+        jobId: String,
+        summary: String = "completed") async throws
+    {
+        let socket = try await self.readySocket()
+        let response = #"{"type":"res","id":"\#(request.id)","ok":true,"payload":{"entries":["# +
+            #"{"ts":1700000000000,"jobId":"\#(jobId)","action":"finished","# +
+            #""status":"ok","summary":"\#(summary)"}]}}"#
+        socket.emitReceiveSuccessOnce(.data(Data(response.utf8)))
+    }
+
+    func fail(_ request: CronGatewayRequest, message: String) async throws {
+        let socket = try await self.readySocket()
+        let response = #"{"type":"res","id":"\#(request.id)","ok":false,"# +
+            #""error":{"code":"INVALID_REQUEST","message":"\#(message)"}}"#
+        socket.emitReceiveSuccessOnce(.data(Data(response.utf8)))
+    }
+
+    func sendFinishedEvent(jobId: String) async throws {
+        let socket = try await self.readySocket()
+        let sequence = await self.requests.eventSequence()
+        let event = #"{"type":"event","event":"cron","seq":\#(sequence),"# +
+            #""payload":{"jobId":"\#(jobId)","action":"finished"}}"#
+        socket.emitReceiveSuccessOnce(.data(Data(event.utf8)))
+    }
+
+    private func readySocket() async throws -> GatewayTestWebSocketTask {
+        let deadline = ContinuousClock.now + .seconds(2)
+        while ContinuousClock.now < deadline {
+            if let socket = self.session.latestTask(), socket.hasPendingReceiveHandler() {
+                return socket
+            }
+            try? await Task.sleep(for: .milliseconds(2))
+        }
+        return try #require(self.session.latestTask())
+    }
+}
+
+@Suite(.serialized)
+@MainActor
+struct CronJobsStoreTests {
+    @Test func `selecting another job sends its history request while the previous request is pending`() async throws {
+        let fixture = CronGatewayFixture()
+        let store = CronJobsStore(gateway: fixture.gateway)
+        defer { store.stop() }
+        store.selectJob("job-a")
+        let firstRequest = try #require(await fixture.waitForRequest(jobId: "job-a"))
+        store.runEntries = [self.entry(jobId: "job-a", summary: "old A")]
+        store.lastError = "old A error"
+
+        store.selectJob("job-b")
+
+        #expect(store.selectedJobId == "job-b")
+        #expect(store.runEntries.isEmpty)
+        #expect(store.lastError == nil)
+        #expect(store.isLoadingRuns)
+        let secondRequest = try #require(await fixture.waitForRequest(jobId: "job-b"))
+        try await fixture.respond(to: secondRequest, jobId: "job-b", summary: "current B")
+        try #require(await self.waitUntil { !store.isLoadingRuns })
+        #expect(store.runEntries.map(\.jobId) == ["job-b"])
+        #expect(store.runEntries.first?.summary == "current B")
+
+        try await fixture.respond(to: firstRequest, jobId: "job-a", summary: "stale A")
+        await Task.yield()
+
+        #expect(store.runEntries.map(\.jobId) == ["job-b"])
+        #expect(store.runEntries.first?.summary == "current B")
+        #expect(!store.isLoadingRuns)
+        #expect(store.lastError == nil)
+        #expect(fixture.session.snapshotMakeCount() == 1)
+        #expect(fixture.session.snapshotCancelCount() == 0)
+        #expect(await fixture.requests.endpointLookupCount() == 2)
+    }
+
+    @Test func `late failure from a superseded job preserves the selected jobs own failure`() async throws {
+        let fixture = CronGatewayFixture()
+        let store = CronJobsStore(gateway: fixture.gateway)
+        defer { store.stop() }
+        store.selectJob("job-a")
+        let firstRequest = try #require(await fixture.waitForRequest(jobId: "job-a"))
+        store.runEntries = [self.entry(jobId: "job-a", summary: "old A")]
+
+        store.selectJob("job-b")
+        #expect(store.runEntries.isEmpty)
+        let selectedRequest = try #require(await fixture.waitForRequest(jobId: "job-b"))
+        try await fixture.fail(selectedRequest, message: "selected job B failed")
+        try #require(await self.waitUntil { !store.isLoadingRuns })
+        let selectedError = try #require(store.lastError)
+        #expect(selectedError.contains("selected job B failed"))
+        #expect(store.runEntries.isEmpty)
+
+        try await fixture.fail(firstRequest, message: "stale job A failed")
+        await Task.yield()
+
+        #expect(store.selectedJobId == "job-b")
+        #expect(store.runEntries.isEmpty)
+        #expect(store.lastError == selectedError)
+        #expect(!store.isLoadingRuns)
+    }
+
+    @Test
+    func `manual refresh replaces the selected jobs pending request without accepting stale success`() async throws {
+        let fixture = CronGatewayFixture()
+        let store = CronJobsStore(gateway: fixture.gateway)
+        defer { store.stop() }
+        store.selectJob("job-a")
+        let originalRequest = try #require(await fixture.waitForRequest(jobId: "job-a"))
+
+        store.refreshRuns(jobId: "job-a")
+
+        let replacement = try #require(await fixture.waitForRequest(jobId: "job-a", occurrence: 1))
+        #expect(store.isLoadingRuns)
+        try await fixture.fail(replacement, message: "manual refresh failed")
+        try #require(await self.waitUntil { !store.isLoadingRuns })
+        let replacementError = try #require(store.lastError)
+
+        try await fixture.respond(to: originalRequest, jobId: "job-a", summary: "stale manual result")
+        await Task.yield()
+
+        #expect(store.runEntries.isEmpty)
+        #expect(store.lastError == replacementError)
+        #expect(!store.isLoadingRuns)
+        #expect(fixture.session.snapshotMakeCount() == 1)
+        #expect(fixture.session.snapshotCancelCount() == 0)
+    }
+
+    @Test func `manual refresh after failure clears the old error and publishes the successful retry`() async throws {
+        let fixture = CronGatewayFixture()
+        let store = CronJobsStore(gateway: fixture.gateway)
+        defer { store.stop() }
+        store.selectJob("job-a")
+        let failedRequest = try #require(await fixture.waitForRequest(jobId: "job-a"))
+        try await fixture.fail(failedRequest, message: "temporary history failure")
+        try #require(await self.waitUntil { store.lastError != nil })
+
+        store.refreshRuns(jobId: "job-a")
+
+        #expect(store.lastError == nil)
+        #expect(store.isLoadingRuns)
+        let retry = try #require(await fixture.waitForRequest(jobId: "job-a", occurrence: 1))
+        try await fixture.respond(to: retry, jobId: "job-a", summary: "recovered history")
+        try #require(await self.waitUntil { !store.isLoadingRuns })
+
+        #expect(store.runEntries.map(\.jobId) == ["job-a"])
+        #expect(store.runEntries.first?.summary == "recovered history")
+        #expect(store.lastError == nil)
+    }
+
+    @Test func `finished events refresh only the job still selected after their debounce`() async throws {
+        let fixture = CronGatewayFixture()
+        let store = CronJobsStore(gateway: fixture.gateway)
+        defer { store.stop() }
+        store.start()
+        try #require(await self.waitUntil { store.jobs.count == 2 })
+        store.selectJob("job-a")
+        let firstRequest = try #require(await fixture.waitForRequest(jobId: "job-a"))
+        try await fixture.respond(to: firstRequest, jobId: "job-a")
+        try #require(await self.waitUntil { !store.isLoadingRuns })
+
+        try await fixture.sendFinishedEvent(jobId: "job-a")
+        try #require(await self.waitUntil { store.isLoadingRuns })
+        store.selectJob("job-b")
+        let selectedRequest = try #require(await fixture.waitForRequest(jobId: "job-b"))
+        try await fixture.respond(to: selectedRequest, jobId: "job-b")
+        try #require(await self.waitUntil { !store.isLoadingRuns })
+
+        #expect(await fixture.waitForRequest(
+            jobId: "job-a",
+            occurrence: 1,
+            timeout: .milliseconds(300)) == nil)
+        #expect(store.runEntries.map(\.jobId) == ["job-b"])
+
+        try await fixture.sendFinishedEvent(jobId: "job-b")
+        let eventRequest = try #require(await fixture.waitForRequest(jobId: "job-b", occurrence: 1))
+        try await fixture.respond(to: eventRequest, jobId: "job-b", summary: "event B")
+        try #require(await self.waitUntil { !store.isLoadingRuns })
+
+        #expect(store.runEntries.map(\.jobId) == ["job-b"])
+        #expect(store.runEntries.first?.summary == "event B")
+        #expect(await fixture.requests.requestCount(method: "cron.runs", jobId: "job-a") == 1)
+    }
+
+    @Test(arguments: ["selection", "manual", "event"], ["success", "failure"])
+    func `stopping the pane rejects late completions from every history entry point`(
+        source: String,
+        outcome: String) async throws
+    {
+        let fixture = CronGatewayFixture()
+        let store = CronJobsStore(gateway: fixture.gateway)
+        defer { store.stop() }
+        if source == "event" {
+            store.start()
+            try #require(await self.waitUntil { store.jobs.count == 2 })
+        }
+        store.selectJob("job-a")
+        var pending = try #require(await fixture.waitForRequest(jobId: "job-a"))
+        if source != "selection" {
+            try await fixture.respond(to: pending, jobId: "job-a", summary: "existing history")
+            try #require(await self.waitUntil { !store.isLoadingRuns })
+            if source == "manual" {
+                store.refreshRuns(jobId: "job-a")
+            } else {
+                try await fixture.sendFinishedEvent(jobId: "job-a")
+            }
+            pending = try #require(await fixture.waitForRequest(jobId: "job-a", occurrence: 1))
+        }
+        let previousHistory = store.runEntries.map(\.summary)
+        let previousError = store.lastError
+
+        store.stop()
+
+        #expect(!store.isLoadingRuns)
+        if outcome == "success" {
+            try await fixture.respond(to: pending, jobId: "job-a", summary: "late history")
+        } else {
+            try await fixture.fail(pending, message: "late history failure")
+        }
+        await Task.yield()
+
+        #expect(store.selectedJobId == "job-a")
+        #expect(store.runEntries.map(\.summary) == previousHistory)
+        #expect(store.lastError == previousError)
+        #expect(!store.isLoadingRuns)
+        #expect(fixture.session.snapshotCancelCount() == 0)
+    }
+
+    @Test func `removing the selected job cancels its pending history before refreshing jobs`() async throws {
+        let fixture = CronGatewayFixture()
+        let store = CronJobsStore(gateway: fixture.gateway)
+        defer { store.stop() }
+        store.selectJob("job-a")
+        let pending = try #require(await fixture.waitForRequest(jobId: "job-a"))
+        store.runEntries = [self.entry(jobId: "job-a", summary: "removed history")]
+
+        await store.removeJob(id: "job-a")
+
+        #expect(store.selectedJobId == nil)
+        #expect(store.runEntries.isEmpty)
+        #expect(!store.isLoadingRuns)
+        #expect(store.jobs.map(\.id) == ["job-b"])
+        try await fixture.respond(to: pending, jobId: "job-a", summary: "late removed job")
+        await Task.yield()
+
+        #expect(store.selectedJobId == nil)
+        #expect(store.runEntries.isEmpty)
+        #expect(store.lastError == nil)
+    }
+
+    @Test
+    func `job list refresh invalidates pending history when another client removed its selected job`() async throws {
+        let fixture = CronGatewayFixture()
+        let store = CronJobsStore(gateway: fixture.gateway)
+        defer { store.stop() }
+        store.selectJob("job-a")
+        let pending = try #require(await fixture.waitForRequest(jobId: "job-a"))
+        store.runEntries = [self.entry(jobId: "job-a", summary: "old history")]
+        await fixture.requests.removeJob("job-a")
+
+        await store.refreshJobs()
+
+        #expect(store.selectedJobId == nil)
+        #expect(store.runEntries.isEmpty)
+        #expect(!store.isLoadingRuns)
+        #expect(store.jobs.map(\.id) == ["job-b"])
+        try await fixture.fail(pending, message: "removed job completed late")
+        await Task.yield()
+
+        #expect(store.runEntries.isEmpty)
+        #expect(store.lastError == nil)
+    }
+
+    @Test func `superseded history never activates the local Gateway or its launch agent`() async throws {
+        try await self.withLocalGatewayRecovery { fixture in
+            let store = CronJobsStore(gateway: fixture.gateway)
+            defer { store.stop() }
+            store.selectJob("job-a")
+            _ = try #require(await fixture.waitForRequest(jobId: "job-a"))
+
+            store.selectJob("job-b")
+
+            let selectedRequest = try #require(await fixture.waitForRequest(jobId: "job-b"))
+            try await fixture.respond(to: selectedRequest, jobId: "job-b")
+            try #require(await self.waitUntil { !store.isLoadingRuns })
+
+            #expect(store.runEntries.map(\.jobId) == ["job-b"])
+            #expect(store.lastError == nil)
+            #expect(await fixture.requests.endpointLookupCount() == 2)
+            #expect(fixture.session.snapshotMakeCount() == 1)
+            #expect(fixture.session.snapshotCancelCount() == 0)
+            #expect(GatewayProcessManager.shared.status == .stopped)
+            #expect(GatewayLaunchAgentManager.testingDaemonCommandCallsSnapshot().isEmpty)
+        }
+    }
+
+    @Test func `uncancelled history transport failures activate the Gateway and retry`() async throws {
+        try await self.withLocalGatewayRecovery(initialRunsFailure: URLError(.networkConnectionLost)) { fixture in
+            let store = CronJobsStore(gateway: fixture.gateway)
+            defer { store.stop() }
+
+            store.selectJob("job-a")
+
+            _ = try #require(await fixture.waitForRequest(jobId: "job-a"))
+            let recoveredRequest = try #require(await fixture.waitForRequest(jobId: "job-a", occurrence: 1))
+            #expect(GatewayProcessManager.shared.status != .stopped)
+            try await fixture.respond(to: recoveredRequest, jobId: "job-a", summary: "recovered history")
+            try #require(await self.waitUntil { !store.isLoadingRuns })
+
+            #expect(store.runEntries.map(\.jobId) == ["job-a"])
+            #expect(store.runEntries.first?.summary == "recovered history")
+            #expect(store.lastError == nil)
+            #expect(await fixture.requests.requestCount(method: "cron.runs", jobId: "job-a") == 2)
+        }
+    }
+
+    @Test func `starting and stopping retains normal scheduler and job refresh behavior`() async throws {
+        let fixture = CronGatewayFixture()
+        let store = CronJobsStore(gateway: fixture.gateway)
+
+        store.start()
+        try #require(await self.waitUntil { store.jobs.count == 2 })
+
+        #expect(store.schedulerEnabled == true)
+        #expect(store.schedulerStorePath == "/tmp/cron-tests")
+        #expect(store.jobs.map(\.id) == ["job-a", "job-b"])
+        #expect(store.lastError == nil)
+        #expect(await fixture.requests.requestCount(method: "cron.status") == 1)
+        #expect(await fixture.requests.requestCount(method: "cron.list") == 1)
+
+        store.stop()
+
+        #expect(!store.isLoadingRuns)
+        #expect(fixture.session.snapshotCancelCount() == 0)
+    }
+
+    private func entry(jobId: String, summary: String) -> CronRunLogEntry {
+        CronRunLogEntry(
+            ts: 1_700_000_000_000,
+            jobId: jobId,
+            action: "finished",
+            status: "ok",
+            error: nil,
+            summary: summary,
+            runAtMs: nil,
+            durationMs: nil,
+            nextRunAtMs: nil)
+    }
+
+    private func withLocalGatewayRecovery(
+        initialRunsFailure: (any Error & Sendable)? = nil,
+        _ operation: (CronGatewayFixture) async throws -> Void) async throws
+    {
+        let isolatedState = FileManager.default.temporaryDirectory
+            .appendingPathComponent("openclaw-autoqa-185-cron-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: isolatedState, withIntermediateDirectories: true)
+        let configURL = isolatedState.appendingPathComponent("openclaw.json")
+        try Data(#"{"gateway":{"mode":"local","port":49185}}"#.utf8).write(to: configURL)
+        defer { try? FileManager.default.removeItem(at: isolatedState) }
+
+        try await TestIsolation.withEnvValues([
+            "OPENCLAW_CONFIG_PATH": configURL.path,
+            "OPENCLAW_STATE_DIR": isolatedState.path,
+        ]) {
+            try await DeviceIdentityStore.withStateDirectory(isolatedState) {
+                let fixture = CronGatewayFixture(
+                    recoveryEligible: true,
+                    initialRunsFailure: initialRunsFailure)
+                let manager = GatewayProcessManager.shared
+                let priorMode = AppStateStore.shared.connectionMode
+                AppStateStore.shared.connectionMode = .local
+                manager._testResetGatewayStartTask()
+                manager.setTestingStatus(.stopped)
+                manager.setTestingConnection(fixture.gateway)
+                manager.setTestingSkipControlChannelRefresh(true)
+                GatewayLaunchAgentManager.setTestingDisableLaunchAgentMarkerURL(
+                    isolatedState.appendingPathComponent("disable-launch-agent"))
+                GatewayLaunchAgentManager.setTestingInterceptDaemonCommands(true)
+                GatewayLaunchAgentManager.setTestingDaemonStatusPayload(
+                    #"{"ok":true,"service":{"loaded":false}}"#)
+                GatewayLaunchAgentManager.clearTestingDaemonCommandCalls()
+                defer {
+                    manager._testResetGatewayStartTask()
+                    manager.setTestingStatus(.stopped)
+                    manager.setTestingConnection(nil)
+                    manager.setTestingSkipControlChannelRefresh(false)
+                    manager.setTestingDesiredActive(false)
+                    GatewayLaunchAgentManager.setTestingDisableLaunchAgentMarkerURL(nil)
+                    GatewayLaunchAgentManager.setTestingInterceptDaemonCommands(false)
+                    GatewayLaunchAgentManager.setTestingDaemonStatusPayload(nil)
+                    GatewayLaunchAgentManager.clearTestingDaemonCommandCalls()
+                    AppStateStore.shared.connectionMode = priorMode
+                }
+
+                do {
+                    try await operation(fixture)
+                    await fixture.gateway.shutdown()
+                } catch {
+                    await fixture.gateway.shutdown()
+                    throw error
+                }
+            }
+        }
+    }
+
+    private func waitUntil(
+        timeout: Duration = .seconds(2),
+        _ condition: @MainActor () -> Bool) async -> Bool
+    {
+        let deadline = ContinuousClock.now + timeout
+        while ContinuousClock.now < deadline {
+            if condition() { return true }
+            try? await Task.sleep(for: .milliseconds(2))
+        }
+        return condition()
+    }
+}
diff --git a/apps/macos/Tests/OpenClawIPCTests/GatewayConnectionControlTests.swift b/apps/macos/Tests/OpenClawIPCTests/GatewayConnectionControlTests.swift
index 2108ab5c9181..a9902c511446 100644
--- a/apps/macos/Tests/OpenClawIPCTests/GatewayConnectionControlTests.swift
+++ b/apps/macos/Tests/OpenClawIPCTests/GatewayConnectionControlTests.swift
@@ -224,6 +224,112 @@ private func assertConfigLookupCannotRecreateRoute(
 }
 
 @Suite(.serialized) struct GatewayConnectionControlTests {
+    @Test @MainActor
+    func `cancelled pending request never activates local gateway recovery`() async throws {
+        try await self.withIsolatedRecoveryFixture { _, _, _ in } operation: { connection, session in
+            let request = Task {
+                try await connection.request(method: "status", params: nil)
+            }
+            try #require(await self.waitForRequest(on: session))
+
+            request.cancel()
+
+            do {
+                _ = try await request.value
+                Issue.record("expected the cancelled caller to throw CancellationError")
+            } catch is CancellationError {} catch {
+                Issue.record("unexpected cancellation error: \(error)")
+            }
+
+            #expect(GatewayProcessManager.shared.status == .stopped)
+            #expect(GatewayLaunchAgentManager.testingDaemonCommandCallsSnapshot().isEmpty)
+            #expect(session.snapshotMakeCount() == 1)
+            #expect(session.latestTask()?.snapshotSendCount() == 2)
+        }
+    }
+
+    @Test @MainActor
+    func `genuine transport failure still activates and retries local gateway recovery`() async throws {
+        try await self.assertUncancelledFailureRecovers(URLError(.networkConnectionLost))
+    }
+
+    @Test @MainActor
+    func `send-side cancellation without caller cancellation still activates gateway recovery`() async throws {
+        try await self.assertUncancelledFailureRecovers(CancellationError())
+    }
+
+    @Test @MainActor
+    func `gateway response errors never activate transport recovery`() async throws {
+        try await self.withIsolatedRecoveryFixture { socket, message, sendIndex in
+            guard sendIndex > 0,
+                  let id = GatewayWebSocketTestSupport.requestID(from: message)
+            else { return }
+            let response = #"{"type":"res","id":"\#(id)","ok":false,"# +
+                #""error":{"code":"INVALID_REQUEST","message":"response rejected"}}"#
+            socket.emitReceiveSuccess(.data(Data(response.utf8)))
+        } operation: { connection, session in
+            do {
+                _ = try await connection.request(method: "status", params: nil)
+                Issue.record("expected the Gateway response error")
+            } catch is GatewayResponseError {} catch {
+                Issue.record("unexpected response error: \(error)")
+            }
+
+            #expect(GatewayProcessManager.shared.status == .stopped)
+            #expect(GatewayLaunchAgentManager.testingDaemonCommandCallsSnapshot().isEmpty)
+            #expect(session.snapshotMakeCount() == 1)
+            #expect(session.latestTask()?.snapshotSendCount() == 2)
+        }
+    }
+
+    @Test func `uncancelled trusted TLS mismatch still repairs its stored pin`() async throws {
+        try await withFakeGatewayTLSKeychain {
+            let url = try #require(URL(string: "wss://gateway.example.ts.net"))
+            let storeKey = "autoqa-185-tls-recovery"
+            GatewayTLSStore.saveFingerprint("old", stableID: storeKey)
+            let route = try #require(GatewayTLSRoute.resolve(
+                url: url,
+                connectionMode: .remote,
+                configuredFingerprint: nil,
+                storedFingerprint: "old",
+                storeKey: storeKey))
+            let failure = GatewayTLSValidationFailure(
+                kind: .pinMismatch,
+                host: "gateway.example.ts.net",
+                storeKey: storeKey,
+                expectedFingerprint: "old",
+                observedFingerprint: "new",
+                systemTrustOk: true,
+                port: 443)
+            let requests = WebSocketMessageRecorder()
+            let session = GatewayTestWebSocketSession(taskFactory: {
+                GatewayTestWebSocketTask(sendHook: { socket, message, sendIndex in
+                    guard sendIndex > 0 else { return }
+                    requests.append(message)
+                    if requests.snapshot().count == 1 {
+                        throw GatewayTLSValidationError(failure: failure, context: "isolated TLS test")
+                    }
+                    guard let id = GatewayWebSocketTestSupport.requestID(from: message) else { return }
+                    socket.emitReceiveSuccess(.data(GatewayWebSocketTestSupport.okResponseData(id: id)))
+                })
+            })
+            let connection = GatewayConnection(
+                testEndpointProvider: {
+                    GatewayConnection.EndpointSnapshot(
+                        config: (url: url, token: nil, password: nil),
+                        tls: route,
+                        routeAuthority: nil)
+                },
+                sessionBox: WebSocketSessionBox(session: session))
+
+            _ = try await connection.request(method: "status", params: nil)
+
+            #expect(GatewayTLSStore.loadFingerprint(stableID: storeKey) == "new")
+            #expect(requests.snapshot().count == 2)
+            await connection.shutdown()
+        }
+    }
+
     @Test func `operator widget capability refresh is shared and retained`() async throws {
         let rawOldSurface = "http://127.0.0.1:18789/__openclaw__/cap/old-token"
         let rawNewSurface = "http://127.0.0.1:18789/__openclaw__/cap/new-token"
@@ -711,6 +817,111 @@ private func assertConfigLookupCannotRecreateRoute(
         }
     }
 
+    @MainActor
+    private func withIsolatedRecoveryFixture<T>(
+        _ sendHook: @escaping GatewayTestWebSocketTask.SendHook,
+        operation: (GatewayConnection, GatewayTestWebSocketSession) async throws -> T) async throws -> T
+    {
+        let isolatedState = FileManager.default.temporaryDirectory
+            .appendingPathComponent("openclaw-gateway-recovery-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: isolatedState, withIntermediateDirectories: true)
+        let configURL = isolatedState.appendingPathComponent("openclaw.json")
+        let port = Int.random(in: 30000...59999)
+        try Data(#"{"gateway":{"mode":"local","port":\#(port)}}"#.utf8).write(to: configURL)
+        defer { try? FileManager.default.removeItem(at: isolatedState) }
+
+        return try await TestIsolation.withEnvValues([
+            "OPENCLAW_PROFILE": "autoqa-185-tests",
+            "OPENCLAW_CONFIG_PATH": configURL.path,
+            "OPENCLAW_STATE_DIR": isolatedState.path,
+        ]) {
+            try await DeviceIdentityStore.withStateDirectory(isolatedState) {
+                let session = GatewayTestWebSocketSession(taskFactory: {
+                    GatewayTestWebSocketTask(sendHook: sendHook)
+                })
+                let connection = GatewayConnection(
+                    endpointProvider: {
+                        GatewayConnection.EndpointSnapshot(
+                            config: (url: URL(string: "ws://127.0.0.1:\(port)")!, token: nil, password: nil),
+                            routeAuthority: nil)
+                    },
+                    supportsSharedEndpointRecovery: true,
+                    activationBindingKeyProvider: { nil },
+                    sessionBox: WebSocketSessionBox(session: session))
+                let manager = GatewayProcessManager.shared
+                let priorMode = AppStateStore.shared.connectionMode
+                AppStateStore.shared.connectionMode = .local
+                manager._testResetGatewayStartTask()
+                manager.setTestingStatus(.stopped)
+                manager.setTestingConnection(connection)
+                manager.setTestingSkipControlChannelRefresh(true)
+                GatewayLaunchAgentManager.setTestingDisableLaunchAgentMarkerURL(
+                    isolatedState.appendingPathComponent("disable-launch-agent"))
+                GatewayLaunchAgentManager.setTestingInterceptDaemonCommands(true)
+                GatewayLaunchAgentManager.setTestingDaemonStatusPayload(
+                    #"{"ok":true,"service":{"loaded":false}}"#)
+                GatewayLaunchAgentManager.clearTestingDaemonCommandCalls()
+                defer {
+                    manager._testResetGatewayStartTask()
+                    manager.setTestingStatus(.stopped)
+                    manager.setTestingConnection(nil)
+                    manager.setTestingSkipControlChannelRefresh(false)
+                    manager.setTestingDesiredActive(false)
+                    GatewayLaunchAgentManager.setTestingDisableLaunchAgentMarkerURL(nil)
+                    GatewayLaunchAgentManager.setTestingInterceptDaemonCommands(false)
+                    GatewayLaunchAgentManager.setTestingDaemonStatusPayload(nil)
+                    GatewayLaunchAgentManager.clearTestingDaemonCommandCalls()
+                    AppStateStore.shared.connectionMode = priorMode
+                }
+
+                do {
+                    let result = try await operation(connection, session)
+                    await connection.shutdown()
+                    return result
+                } catch {
+                    await connection.shutdown()
+                    throw error
+                }
+            }
+        }
+    }
+
+    @MainActor
+    private func assertUncancelledFailureRecovers(_ failure: any Error & Sendable) async throws {
+        let requests = WebSocketMessageRecorder()
+        try await self.withIsolatedRecoveryFixture { socket, message, sendIndex in
+            guard sendIndex > 0,
+                  let id = GatewayWebSocketTestSupport.requestID(from: message),
+                  let data = Self.messageData(message),
+                  let frame = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+            else { return }
+            if frame["method"] as? String == "status" {
+                requests.append(message)
+                if requests.snapshot().count == 1 {
+                    throw failure
+                }
+            }
+            socket.emitReceiveSuccess(.data(GatewayWebSocketTestSupport.okResponseData(id: id)))
+        } operation: { connection, session in
+            _ = try await connection.request(method: "status", params: nil)
+
+            #expect(GatewayProcessManager.shared.status != .stopped)
+            #expect(requests.snapshot().count == 2)
+            #expect(session.snapshotMakeCount() >= 1)
+        }
+    }
+
+    private func waitForRequest(on session: GatewayTestWebSocketSession) async -> Bool {
+        let deadline = ContinuousClock.now + .seconds(2)
+        while ContinuousClock.now < deadline {
+            if session.latestTask()?.snapshotSendCount() ?? 0 >= 2 {
+                return true
+            }
+            try? await Task.sleep(for: .milliseconds(2))
+        }
+        return false
+    }
+
     private func assertDeviceTokenIsolation(
         routeA: (url: URL, owner: String),
         routeB: (url: URL, owner: String)

From f33952eca4cb9e84724785e90e1ee3665023dd3e Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 11:20:47 -0700
Subject: [PATCH 054/124] fix(qa): resolve time runtime in lab build (#127310)

Amp-Thread-ID: https://ampcode.com/threads/T-01a021f4-b547-7788-a916-d4a94cbd3e3b

Co-authored-by: Amp <amp@ampcode.com>
---
 extensions/qa-lab/web/vite.config.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/extensions/qa-lab/web/vite.config.ts b/extensions/qa-lab/web/vite.config.ts
index 941719aa7689..d59aa35e3837 100644
--- a/extensions/qa-lab/web/vite.config.ts
+++ b/extensions/qa-lab/web/vite.config.ts
@@ -15,6 +15,10 @@ export default defineConfig({
         import.meta.dirname,
         "../../../packages/normalization-core/src/utf16-slice.ts",
       ),
+      "openclaw/plugin-sdk/time-runtime": path.resolve(
+        import.meta.dirname,
+        "../../../packages/plugin-sdk/src/time-runtime.ts",
+      ),
     },
   },
   build: {

From 1da74794b6083a4975a3e892f852a9c881a3a027 Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Fri, 21 Aug 2026 11:24:22 -0700
Subject: [PATCH 055/124] fix(release): establish immutable release plan
 contract (#127008)

* fix(release): define immutable release plan contract

* fix(release): harden immutable plan authority

* fix(release): tighten release plan authority

* fix(release): share plugin publication authority

* fix(release): verify plan authority remotely

* fix(release): track ClawHub publication authorities

* fix(release): trust remote tooling tag identity

* fix(release): close plugin publication authority

* fix(release): align npm authority selection

* fix(release): bind plans to validation intent

* fix(release): require qualification cadence

* fix(release): reject lossy canonical values

* fix(release): narrow qualification cadence

* fix(release): bind plan parser dependency

* fix(release): add tagless diagnostic plans

* fix(release): attest release plan parser tree

* fix(release): isolate verified plan parser snapshot

* fix(release): verify plan tooling before execution
---
 .github/workflows/plugin-npm-release.yml      |    7 +-
 config/knip.config.ts                         |    2 +
 scripts/lib/plugin-clawhub-release.ts         |  156 +--
 scripts/lib/plugin-npm-release.ts             |  392 +-----
 scripts/lib/plugin-publication-candidates.ts  |  127 ++
 scripts/lib/plugin-publication-collector.ts   |  369 +++++
 scripts/plugin-npm-release-check.ts           |   26 +-
 scripts/release-plan-contract.d.mts           |   47 +
 scripts/release-plan-contract.mjs             |  442 ++++++
 scripts/release-plan-producer-core.mts        |  633 +++++++++
 scripts/release-plan-producer.mts             |  544 ++++++++
 scripts/release-validation-intent.d.mts       |   35 +
 scripts/release-validation-intent.mjs         |   56 +
 .../release-plan-lock-v1.compatibility.json   |    1 +
 test/fixtures/release-plan-v1.source.json     |    1 +
 test/helpers/publishable-plugin-fixture.ts    |    3 +-
 test/plugin-clawhub-release.test.ts           |   49 +-
 test/plugin-npm-release.test.ts               |  113 +-
 ...lugin-npm-extended-stable-workflow.test.ts |   23 +
 test/scripts/release-plan-contract.test.ts    |  368 +++++
 test/scripts/release-plan-producer.test.ts    | 1201 +++++++++++++++++
 .../scripts/release-validation-intent.test.ts |   68 +
 22 files changed, 4180 insertions(+), 483 deletions(-)
 create mode 100644 scripts/lib/plugin-publication-candidates.ts
 create mode 100644 scripts/lib/plugin-publication-collector.ts
 create mode 100644 scripts/release-plan-contract.d.mts
 create mode 100644 scripts/release-plan-contract.mjs
 create mode 100644 scripts/release-plan-producer-core.mts
 create mode 100644 scripts/release-plan-producer.mts
 create mode 100644 scripts/release-validation-intent.d.mts
 create mode 100644 scripts/release-validation-intent.mjs
 create mode 100644 test/fixtures/release-plan-lock-v1.compatibility.json
 create mode 100644 test/fixtures/release-plan-v1.source.json
 create mode 100644 test/scripts/release-plan-contract.test.ts
 create mode 100644 test/scripts/release-plan-producer.test.ts
 create mode 100644 test/scripts/release-validation-intent.test.ts

diff --git a/.github/workflows/plugin-npm-release.yml b/.github/workflows/plugin-npm-release.yml
index c9b07fe23f14..51168c8646a0 100644
--- a/.github/workflows/plugin-npm-release.yml
+++ b/.github/workflows/plugin-npm-release.yml
@@ -7,9 +7,12 @@ on:
       - main
     paths:
       - ".github/workflows/plugin-npm-release.yml"
+      - ".github/actions/setup-node-env/**"
       - "extensions/**"
       - "package.json"
-      - "packages/normalization-core/**"
+      - "pnpm-lock.yaml"
+      - "packages/normalization-core/src/**"
+      - "packages/plugin-package-contract/src/**"
       - "scripts/generate-npm-package-lock.mjs"
       - "scripts/generate-npm-package-lock.mts"
       - "scripts/lib/npm-publish-plan.mjs"
@@ -19,6 +22,8 @@ on:
       - "scripts/lib/plugin-npm-package-manifest.mts"
       - "scripts/lib/tsx-cli-shim.mjs"
       - "scripts/lib/plugin-npm-release.ts"
+      - "scripts/lib/plugin-publication-candidates.ts"
+      - "scripts/lib/plugin-publication-collector.ts"
       - "scripts/lib/actions-artifact-archive.mjs"
       - "scripts/plugin-npm-publish.sh"
       - "scripts/plugin-publication-artifact.mjs"
diff --git a/config/knip.config.ts b/config/knip.config.ts
index eae5a7fb8266..8977eb65ba6f 100644
--- a/config/knip.config.ts
+++ b/config/knip.config.ts
@@ -144,6 +144,8 @@ const rootEntries = [
   "scripts/print-cli-backend-live-metadata.ts!",
   // Workflow/package-script entrypoints are not imported from production modules.
   "scripts/openclaw-cross-os-release-checks.ts!",
+  "scripts/release-plan-producer-core.mts!",
+  "scripts/release-plan-producer.mts!",
   // Spawned by the agent concurrency benchmark; no static import edge exists.
   "scripts/bench-agent-concurrency-worker.ts!",
   // Spawned by the durable task registry churn benchmark in a fresh GC-enabled process.
diff --git a/scripts/lib/plugin-clawhub-release.ts b/scripts/lib/plugin-clawhub-release.ts
index 9e3c39c5b92b..d9207f9bb17c 100644
--- a/scripts/lib/plugin-clawhub-release.ts
+++ b/scripts/lib/plugin-clawhub-release.ts
@@ -2,70 +2,39 @@
 import { execFileSync } from "node:child_process";
 import { resolve } from "node:path";
 import { truncateUtf16Safe } from "../../packages/normalization-core/src/utf16-slice.js";
-import { validateExternalCodePluginPackageJson } from "../../packages/plugin-package-contract/src/index.ts";
 import { retryClawHubRead } from "../../src/infra/clawhub-retry.js";
 import { runTasksWithConcurrency } from "../../src/utils/run-with-concurrency.js";
 import { readBoundedResponseText } from "./bounded-response.mjs";
 import {
   assertPluginReleaseDependencyFreshness,
-  collectExtensionPackageJsonCandidates,
   collectChangedPathsFromGitRange,
   collectChangedExtensionIdsFromPaths,
-  collectPublishablePluginPackageErrors,
-  collectRequiredLatestDependencies,
-  isPluginExternalPublicationDeferred,
   assertPluginReleaseVersionFloors,
   parsePluginReleaseArgs,
-  resolvePublishablePluginVersion,
   resolveGitCommitSha,
   resolveChangedPublishablePluginPackages,
   resolveSelectedPublishablePluginPackages,
   type GitRangeSelection,
   type NpmLatestVersionResolver,
   type PluginReleaseSelectionMode,
-  type RequiredLatestDependency,
 } from "./plugin-npm-release.ts";
+import {
+  collectExtensionPackageJsonCandidates,
+  hasPluginPublicationSharedAuthorityChanges,
+  PLUGIN_PUBLICATION_SHARED_AUTHORITY_PATHS,
+} from "./plugin-publication-candidates.ts";
+import {
+  collectPublishablePluginPackagesFromCandidates,
+  type PluginPackageJson,
+  type PublishablePluginPackage,
+} from "./plugin-publication-collector.ts";
 
 export {
   assertPluginReleaseDependencyFreshness,
   assertPluginReleaseVersionFloors,
   parsePluginReleaseArgs,
 };
-
-type PluginPackageJson = {
-  name?: string;
-  version?: string;
-  private?: boolean;
-  openclaw?: {
-    extensions?: string[];
-    install?: {
-      npmSpec?: string;
-    };
-    compat?: {
-      pluginApi?: string;
-      minGatewayVersion?: string;
-    };
-    build?: {
-      bundledDist?: boolean;
-      openclawVersion?: string;
-      pluginSdkVersion?: string;
-    };
-    release?: {
-      publishToClawHub?: boolean;
-      publishToNpm?: boolean;
-    };
-  };
-};
-
-export type PublishablePluginPackage = {
-  extensionId: string;
-  packageDir: string;
-  packageName: string;
-  version: string;
-  channel: "stable" | "alpha" | "beta";
-  publishTag: "latest" | "alpha" | "beta" | "extended-stable";
-  requiredLatestDependencies?: RequiredLatestDependency[];
-};
+export type { PublishablePluginPackage } from "./plugin-publication-collector.ts";
 
 type PluginReleasePlanItem = PublishablePluginPackage & {
   alreadyPublished: boolean;
@@ -110,16 +79,10 @@ const CLAWHUB_ERROR_BODY_MAX_CHARS = 400;
 const CLAWHUB_RELEASE_PLAN_CONCURRENCY = 8;
 const OPENCLAW_PLUGIN_CLAWHUB_REPOSITORY = "openclaw/openclaw";
 const OPENCLAW_PLUGIN_CLAWHUB_WORKFLOW_FILENAME = "plugin-clawhub-release.yml";
-const SAFE_EXTENSION_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
-const CLAWHUB_SHARED_RELEASE_INPUT_PATHS = [
+const CLAWHUB_RELEASE_AUTHORITY_PATHS = [
   ".github/workflows/plugin-clawhub-release.yml",
   ".github/actions/setup-node-env",
-  "package.json",
-  "pnpm-lock.yaml",
-  "packages/plugin-package-contract/src/index.ts",
   "scripts/lib/bounded-response.mjs",
-  "scripts/lib/npm-publish-plan.mjs",
-  "scripts/lib/release-version.mjs",
   "scripts/lib/plugin-npm-release.ts",
   "scripts/lib/plugin-clawhub-release.ts",
   "scripts/openclaw-npm-release-check.ts",
@@ -268,82 +231,11 @@ export function collectClawHubPublishablePluginPackages(
   rootDir = resolve("."),
   filters: ClawHubPublishablePluginPackageFilters = {},
 ): PublishablePluginPackage[] {
-  const publishable: PublishablePluginPackage[] = [];
-  const validationErrors: string[] = [];
-  const selectedExtensionIds = new Set(filters.extensionIds ?? []);
-  const selectedPackageNames = new Set(filters.packageNames ?? []);
-  const hasSelectedExtensionIds = Array.isArray(filters.extensionIds);
-  const hasSelectedPackageNames = Array.isArray(filters.packageNames);
-
-  for (const candidate of collectExtensionPackageJsonCandidates(rootDir)) {
-    const { extensionId, packageDir, packageJson } = candidate;
-    if (hasSelectedExtensionIds && !selectedExtensionIds.has(extensionId)) {
-      continue;
-    }
-    const packageName = packageJson.name?.trim() ?? "";
-    if (hasSelectedPackageNames && !selectedPackageNames.has(packageName)) {
-      continue;
-    }
-    if (isPluginExternalPublicationDeferred(packageJson)) {
-      continue;
-    }
-    if (packageJson.openclaw?.release?.publishToClawHub !== true) {
-      continue;
-    }
-    if (!SAFE_EXTENSION_ID_RE.test(extensionId)) {
-      validationErrors.push(
-        `${extensionId}: extension directory name must match ^[a-z0-9][a-z0-9._-]*$ for ClawHub publish.`,
-      );
-      continue;
-    }
-
-    const errors = collectPublishablePluginPackageErrors(candidate);
-    if (errors.length > 0) {
-      validationErrors.push(...errors.map((error) => `${extensionId}: ${error}`));
-      continue;
-    }
-    const contractValidation = validateExternalCodePluginPackageJson(packageJson);
-    if (contractValidation.issues.length > 0) {
-      validationErrors.push(
-        ...contractValidation.issues.map((issue) => `${extensionId}: ${issue.message}`),
-      );
-      continue;
-    }
-
-    const resolvedVersion = resolvePublishablePluginVersion({
-      extensionId,
-      packageJson,
-      validationErrors,
-    });
-    if (!resolvedVersion) {
-      continue;
-    }
-    const { version, parsedVersion } = resolvedVersion;
-    const requiredLatestDependencies = collectRequiredLatestDependencies(packageJson).dependencies;
-
-    publishable.push({
-      extensionId,
-      packageDir,
-      packageName,
-      version,
-      channel: parsedVersion.channel,
-      publishTag:
-        parsedVersion.channel === "alpha"
-          ? "alpha"
-          : parsedVersion.channel === "beta"
-            ? "beta"
-            : "latest",
-      ...(requiredLatestDependencies.length > 0 ? { requiredLatestDependencies } : {}),
-    });
-  }
-
-  if (validationErrors.length > 0) {
-    throw new Error(
-      `Publishable ClawHub plugin metadata validation failed:\n${validationErrors.map((error) => `- ${error}`).join("\n")}`,
-    );
-  }
-
-  return publishable.toSorted((left, right) => left.packageName.localeCompare(right.packageName));
+  return collectPublishablePluginPackagesFromCandidates(
+    collectExtensionPackageJsonCandidates(rootDir),
+    "clawhub",
+    filters,
+  );
 }
 
 export function collectPluginClawHubReleasePathsFromGitRange(params: {
@@ -359,7 +251,8 @@ function collectPluginClawHubRelevantPathsFromGitRange(params: {
 }): string[] {
   return collectPluginClawHubReleasePathsFromGitRangeForPathspecs(params, [
     "extensions",
-    ...CLAWHUB_SHARED_RELEASE_INPUT_PATHS,
+    ...PLUGIN_PUBLICATION_SHARED_AUTHORITY_PATHS,
+    ...CLAWHUB_RELEASE_AUTHORITY_PATHS,
   ]);
 }
 
@@ -378,10 +271,13 @@ function collectPluginClawHubReleasePathsFromGitRangeForPathspecs(
 }
 
 function hasSharedClawHubReleaseInputChanges(changedPaths: readonly string[]) {
-  return changedPaths.some((path) =>
-    CLAWHUB_SHARED_RELEASE_INPUT_PATHS.some(
-      (sharedPath) => path === sharedPath || path.startsWith(`${sharedPath}/`),
-    ),
+  return (
+    hasPluginPublicationSharedAuthorityChanges(changedPaths) ||
+    changedPaths.some((path) =>
+      CLAWHUB_RELEASE_AUTHORITY_PATHS.some(
+        (authorityPath) => path === authorityPath || path.startsWith(`${authorityPath}/`),
+      ),
+    )
   );
 }
 
diff --git a/scripts/lib/plugin-npm-release.ts b/scripts/lib/plugin-npm-release.ts
index 5c1c5dadaae4..74d0a3b4b7dc 100644
--- a/scripts/lib/plugin-npm-release.ts
+++ b/scripts/lib/plugin-npm-release.ts
@@ -1,73 +1,28 @@
 // Plugin Npm Release script supports OpenClaw repository automation.
 import { execFileSync } from "node:child_process";
-import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { expectDefined } from "../../packages/normalization-core/src/expect.js";
-import { normalizeOptionalString } from "../../packages/normalization-core/src/string-coerce.js";
-import { validateExternalCodePluginPackageJson } from "../../packages/plugin-package-contract/src/index.ts";
-import { resolveNpmPublishPlan } from "./npm-publish-plan.mjs";
-import { collectReleaseVersionFloorErrors, parseReleaseVersion } from "./release-version.mjs";
+import {
+  collectExtensionPackageJsonCandidates,
+  hasPluginNpmReleaseAuthorityChanges,
+  PLUGIN_NPM_RELEASE_AUTHORITY_PATHS,
+} from "./plugin-publication-candidates.ts";
+import {
+  assertUniquePublishablePluginPackageSources,
+  collectPublishablePluginPackagesFromCandidates,
+  type PluginPackageJson,
+  type PublishablePluginPackage,
+  type PublishablePluginPackageFilters,
+} from "./plugin-publication-collector.ts";
+import { collectReleaseVersionFloorErrors } from "./release-version.mjs";
 
-type PluginPackageJson = {
-  name?: string;
-  version?: string;
-  type?: string;
-  private?: boolean;
-  dependencies?: Record<string, unknown>;
-  optionalDependencies?: Record<string, unknown>;
-  repository?:
-    | string
-    | {
-        type?: string;
-        url?: string;
-      };
-  openclaw?: {
-    extensions?: string[];
-    install?: {
-      defaultChoice?: string;
-      minHostVersion?: string;
-      npmSpec?: string;
-    };
-    compat?: {
-      pluginApi?: string;
-      minGatewayVersion?: string;
-    };
-    build?: {
-      bundledDist?: boolean;
-      openclawVersion?: string;
-      pluginSdkVersion?: string;
-    };
-    release?: {
-      publishToClawHub?: boolean;
-      publishToNpm?: boolean;
-      requireLatestDependencies?: unknown;
-    };
-  };
-};
-
-/** Explicit core ownership defers staged external publication until the plugin is externalized. */
-export function isPluginExternalPublicationDeferred(packageJson: {
-  openclaw?: { build?: { bundledDist?: unknown } };
-}): boolean {
-  return packageJson.openclaw?.build?.bundledDist === true;
-}
-
-export type RequiredLatestDependency = {
-  packageName: string;
-  version: string;
-};
-
-export type PublishablePluginPackage = {
-  extensionId: string;
-  packageDir: string;
-  packageName: string;
-  version: string;
-  channel: "stable" | "alpha" | "beta";
-  publishTag: "latest" | "alpha" | "beta" | "extended-stable";
-  installNpmSpec?: string;
-  requiredLatestDependencies?: RequiredLatestDependency[];
-};
+export {
+  collectPublishablePluginPackageErrors,
+  OPENCLAW_PLUGIN_NPM_REPOSITORY_URL,
+} from "./plugin-publication-collector.ts";
+export type { PublishablePluginPackage } from "./plugin-publication-collector.ts";
 
 type PluginReleasePlanItem = PublishablePluginPackage & {
   alreadyPublished: boolean;
@@ -86,6 +41,11 @@ export type GitRangeSelection = {
   headRef: string;
 };
 
+type PluginNpmGitRangeSelection = {
+  authorityChanged: boolean;
+  changedExtensionIds: string[];
+};
+
 type ParsedPluginReleaseArgs = {
   selection: string[];
   selectionMode?: PluginReleaseSelectionMode;
@@ -108,125 +68,12 @@ function parsePluginNpmDistTagOverride(value: string | undefined): "extended-sta
   throw new Error(`Unknown npm dist-tag override: ${value}. Expected "extended-stable".`);
 }
 
-type PublishablePluginPackageCandidate<TPackageJson extends PluginPackageJson = PluginPackageJson> =
-  {
-    extensionId: string;
-    packageDir: string;
-    packageJson: TPackageJson;
-    readmeText?: string;
-  };
-
-export const OPENCLAW_PLUGIN_NPM_REPOSITORY_URL = "https://github.com/openclaw/openclaw";
 const PLUGIN_NPM_VIEW_TIMEOUT_MS = 60_000;
 
-export function collectRequiredLatestDependencies(packageJson: PluginPackageJson): {
-  dependencies: RequiredLatestDependency[];
-  errors: string[];
-} {
-  const configured = packageJson.openclaw?.release?.requireLatestDependencies;
-  if (configured === undefined) {
-    return { dependencies: [], errors: [] };
-  }
-  if (!Array.isArray(configured)) {
-    return {
-      dependencies: [],
-      errors: ["openclaw.release.requireLatestDependencies must be an array of package names."],
-    };
-  }
-
-  const runtimeDependencies = {
-    ...packageJson.dependencies,
-    ...packageJson.optionalDependencies,
-  };
-  const dependencies: RequiredLatestDependency[] = [];
-  const errors: string[] = [];
-  const seen = new Set<string>();
-
-  for (const value of configured) {
-    if (typeof value !== "string" || !value.trim()) {
-      errors.push(
-        "openclaw.release.requireLatestDependencies must contain only non-empty package names.",
-      );
-      continue;
-    }
-    const packageName = value.trim();
-    if (seen.has(packageName)) {
-      errors.push(
-        `openclaw.release.requireLatestDependencies must not contain duplicate package names; found "${packageName}".`,
-      );
-      continue;
-    }
-    seen.add(packageName);
-
-    const version = runtimeDependencies[packageName];
-    if (typeof version !== "string" || !version.trim()) {
-      errors.push(
-        `openclaw.release.requireLatestDependencies must reference package.json dependencies or optionalDependencies; "${packageName}" is not a runtime dependency.`,
-      );
-      continue;
-    }
-    dependencies.push({ packageName, version: version.trim() });
-  }
-
-  return { dependencies, errors };
-}
-
 function readPluginPackageJson(path: string): unknown {
   return JSON.parse(readFileSync(path, "utf8"));
 }
 
-function readOptionalTextFile(path: string): string | undefined {
-  try {
-    return readFileSync(path, "utf8");
-  } catch {
-    return undefined;
-  }
-}
-
-export function collectExtensionPackageJsonCandidates<
-  TPackageJson extends PluginPackageJson = PluginPackageJson,
->(rootDir = resolve(".")): PublishablePluginPackageCandidate<TPackageJson>[] {
-  const extensionsDir = join(rootDir, "extensions");
-  const dirs = readdirSync(extensionsDir, { withFileTypes: true }).filter((entry) =>
-    entry.isDirectory(),
-  );
-
-  const candidates: PublishablePluginPackageCandidate<TPackageJson>[] = [];
-  for (const dir of dirs) {
-    const packageDir = `extensions/${dir.name}`;
-    const absolutePackageDir = join(extensionsDir, dir.name);
-    const packageJsonPath = join(absolutePackageDir, "package.json");
-    try {
-      candidates.push({
-        extensionId: dir.name,
-        packageDir,
-        packageJson: readPluginPackageJson(packageJsonPath) as TPackageJson,
-        readmeText: readOptionalTextFile(join(absolutePackageDir, "README.md")),
-      });
-    } catch {
-      continue;
-    }
-  }
-
-  return candidates;
-}
-
-export function resolvePublishablePluginVersion(params: {
-  extensionId: string;
-  packageJson: Pick<PluginPackageJson, "version">;
-  validationErrors: string[];
-}): { version: string; parsedVersion: NonNullable<ReturnType<typeof parseReleaseVersion>> } | null {
-  const version = params.packageJson.version?.trim() ?? "";
-  const parsedVersion = parseReleaseVersion(version);
-  if (parsedVersion === null) {
-    params.validationErrors.push(
-      `${params.extensionId}: package.json version must match YYYY.M.PATCH, YYYY.M.PATCH-N, YYYY.M.PATCH-alpha.N, or YYYY.M.PATCH-beta.N; found "${version}".`,
-    );
-    return null;
-  }
-  return { version, parsedVersion };
-}
-
 function normalizeGitDiffPath(path: string): string {
   return path.trim().replaceAll("\\", "/");
 }
@@ -354,151 +201,28 @@ function readRequiredArgValue(
   return value;
 }
 
-export function collectPublishablePluginPackageErrors(
-  candidate: PublishablePluginPackageCandidate,
-): string[] {
-  const { packageJson } = candidate;
-  const errors: string[] = [];
-  const packageName = packageJson.name?.trim() ?? "";
-  const packageVersion = packageJson.version?.trim() ?? "";
-  const installNpmSpec = normalizeOptionalString(packageJson.openclaw?.install?.npmSpec);
-  const repositoryUrl =
-    typeof packageJson.repository === "string"
-      ? packageJson.repository.trim()
-      : (packageJson.repository?.url?.trim() ?? "");
-  const extensions = packageJson.openclaw?.extensions ?? [];
-  const requiredLatestDependencies = collectRequiredLatestDependencies(packageJson);
-
-  if (!packageName.startsWith("@openclaw/")) {
-    errors.push(
-      `package name must start with "@openclaw/"; found "${packageName || "<missing>"}".`,
-    );
-  }
-  if (packageJson.private === true) {
-    errors.push("package.json private must not be true.");
-  }
-  if (packageJson.type !== "module") {
-    errors.push('package.json type must be "module" so built .js runtime entries load as ESM.');
-  }
-  if (!candidate.readmeText?.trim()) {
-    errors.push("README.md must exist and contain package documentation.");
-  }
-  if (repositoryUrl !== OPENCLAW_PLUGIN_NPM_REPOSITORY_URL) {
-    errors.push(
-      `package.json repository.url must be "${OPENCLAW_PLUGIN_NPM_REPOSITORY_URL}" so npm provenance can validate GitHub trusted publishing; found "${repositoryUrl || "<missing>"}".`,
-    );
-  }
-  if (!packageVersion) {
-    errors.push("package.json version must be non-empty.");
-  } else if (parseReleaseVersion(packageVersion) === null) {
-    errors.push(
-      `package.json version must match YYYY.M.PATCH, YYYY.M.PATCH-N, YYYY.M.PATCH-alpha.N, or YYYY.M.PATCH-beta.N; found "${packageVersion}".`,
-    );
-  }
-  if (!Array.isArray(extensions) || extensions.length === 0) {
-    errors.push("openclaw.extensions must contain at least one entry.");
-  }
-  if (extensions.some((entry) => typeof entry !== "string" || !entry.trim())) {
-    errors.push("openclaw.extensions must contain only non-empty strings.");
-  }
-  if (!installNpmSpec) {
-    errors.push("openclaw.install.npmSpec must be a non-empty string for publishable plugins.");
-  }
-  errors.push(...requiredLatestDependencies.errors);
-  errors.push(
-    ...validateExternalCodePluginPackageJson(packageJson).issues.map((issue) => issue.message),
-  );
-
-  return errors;
-}
-
-type PublishablePluginPackageFilters = {
-  extensionIds?: readonly string[];
-  packageNames?: readonly string[];
-  npmDistTag?: "extended-stable";
-};
-
 export function collectPublishablePluginPackages(
   rootDir = resolve("."),
   filters: PublishablePluginPackageFilters = {},
 ): PublishablePluginPackage[] {
-  const publishable: PublishablePluginPackage[] = [];
-  const validationErrors: string[] = [];
-  const selectedExtensionIds = new Set(filters.extensionIds ?? []);
-  const selectedPackageNames = new Set(filters.packageNames ?? []);
-  const hasSelectedExtensionIds = Array.isArray(filters.extensionIds);
-  const hasSelectedPackageNames = Array.isArray(filters.packageNames);
-
-  for (const candidate of collectExtensionPackageJsonCandidates(rootDir)) {
-    const { extensionId, packageDir, packageJson } = candidate;
-    if (hasSelectedExtensionIds && !selectedExtensionIds.has(extensionId)) {
-      continue;
-    }
-    const packageName = packageJson.name?.trim() ?? "";
-    if (hasSelectedPackageNames && !selectedPackageNames.has(packageName)) {
-      continue;
-    }
-    if (isPluginExternalPublicationDeferred(packageJson)) {
-      continue;
-    }
-    if (packageJson.openclaw?.release?.publishToNpm !== true) {
-      continue;
-    }
-
-    const errors = collectPublishablePluginPackageErrors(candidate);
-    if (errors.length > 0) {
-      validationErrors.push(...errors.map((error) => `${extensionId}: ${error}`));
-      continue;
-    }
-
-    const resolvedVersion = resolvePublishablePluginVersion({
-      extensionId,
-      packageJson,
-      validationErrors,
-    });
-    if (!resolvedVersion) {
-      continue;
-    }
-    const { version, parsedVersion } = resolvedVersion;
-    const requiredLatestDependencies = collectRequiredLatestDependencies(packageJson).dependencies;
-
-    publishable.push({
-      extensionId,
-      packageDir,
-      packageName,
-      version,
-      channel: parsedVersion.channel,
-      publishTag: resolveNpmPublishPlan(version, undefined, filters.npmDistTag).publishTag,
-      installNpmSpec: normalizeOptionalString(packageJson.openclaw?.install?.npmSpec),
-      ...(requiredLatestDependencies.length > 0 ? { requiredLatestDependencies } : {}),
-    });
-  }
-
-  if (filters.npmDistTag === "extended-stable") {
-    const rootPackage = readPluginPackageJson(join(rootDir, "package.json")) as PluginPackageJson;
-    const rootVersion = rootPackage.version?.trim() ?? "";
-    for (const plugin of publishable) {
-      if (plugin.version !== rootVersion) {
-        validationErrors.push(
-          `${plugin.extensionId}: package version ${plugin.version} must match root package version ${rootVersion || "<missing>"} for extended-stable publication.`,
-        );
-      }
-    }
-  }
-
-  if (validationErrors.length > 0) {
-    throw new Error(
-      `Publishable plugin metadata validation failed:\n${validationErrors.map((error) => `- ${error}`).join("\n")}`,
-    );
-  }
-
-  return publishable.toSorted((left, right) => left.packageName.localeCompare(right.packageName));
+  const rootVersion =
+    filters.npmDistTag === "extended-stable"
+      ? ((
+          readPluginPackageJson(join(rootDir, "package.json")) as PluginPackageJson
+        ).version?.trim() ?? "")
+      : undefined;
+  return collectPublishablePluginPackagesFromCandidates(
+    collectExtensionPackageJsonCandidates(rootDir),
+    "npm",
+    { ...filters, rootVersion },
+  );
 }
 
 export function resolveSelectedPublishablePluginPackages(params: {
   plugins: PublishablePluginPackage[];
   selection: string[];
 }): PublishablePluginPackage[] {
+  assertUniquePublishablePluginPackageSources(params.plugins, "Plugin selection");
   if (params.selection.length === 0) {
     return params.plugins;
   }
@@ -600,17 +324,19 @@ export function collectChangedPathsFromGitRange(params: {
     .map((path) => normalizeGitDiffPath(path));
 }
 
-export function collectChangedExtensionIdsFromGitRange(params: {
+export function collectPluginNpmGitRangeSelection(params: {
   rootDir?: string;
   gitRange: GitRangeSelection;
-}): string[] {
-  return collectChangedExtensionIdsFromPaths(
-    collectChangedPathsFromGitRange({
-      rootDir: params.rootDir,
-      gitRange: params.gitRange,
-      pathspecs: ["extensions"],
-    }),
-  );
+}): PluginNpmGitRangeSelection {
+  const changedPaths = collectChangedPathsFromGitRange({
+    rootDir: params.rootDir,
+    gitRange: params.gitRange,
+    pathspecs: ["extensions", ...PLUGIN_NPM_RELEASE_AUTHORITY_PATHS],
+  });
+  return {
+    authorityChanged: hasPluginNpmReleaseAuthorityChanges(changedPaths),
+    changedExtensionIds: collectChangedExtensionIdsFromPaths(changedPaths),
+  };
 }
 
 export function resolveChangedPublishablePluginPackages(params: {
@@ -763,17 +489,19 @@ export function collectPluginReleasePlan(params?: {
   gitRange?: GitRangeSelection;
   npmDistTag?: "extended-stable";
 }): PluginReleasePlan {
-  const changedExtensionIds = params?.gitRange
-    ? collectChangedExtensionIdsFromGitRange({
+  const gitRangeSelection = params?.gitRange
+    ? collectPluginNpmGitRangeSelection({
         rootDir: params.rootDir,
         gitRange: params.gitRange,
       })
-    : [];
+    : undefined;
   const allPublishable = collectPublishablePluginPackages(params?.rootDir, {
     extensionIds:
-      params?.selectionMode === "all-publishable" || !params?.gitRange
+      params?.selectionMode === "all-publishable" ||
+      !gitRangeSelection ||
+      gitRangeSelection.authorityChanged
         ? undefined
-        : changedExtensionIds,
+        : gitRangeSelection.changedExtensionIds,
     packageNames: params?.selection && params.selection.length > 0 ? params.selection : undefined,
     npmDistTag: params?.npmDistTag,
   });
@@ -785,11 +513,13 @@ export function collectPluginReleasePlan(params?: {
             plugins: allPublishable,
             selection: params.selection,
           })
-        : params?.gitRange
-          ? resolveChangedPublishablePluginPackages({
-              plugins: allPublishable,
-              changedExtensionIds,
-            })
+        : gitRangeSelection
+          ? gitRangeSelection.authorityChanged
+            ? allPublishable
+            : resolveChangedPublishablePluginPackages({
+                plugins: allPublishable,
+                changedExtensionIds: gitRangeSelection.changedExtensionIds,
+              })
           : allPublishable;
 
   const explicitPublishSelection =
diff --git a/scripts/lib/plugin-publication-candidates.ts b/scripts/lib/plugin-publication-candidates.ts
new file mode 100644
index 000000000000..2473d4b41db3
--- /dev/null
+++ b/scripts/lib/plugin-publication-candidates.ts
@@ -0,0 +1,127 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type {
+  PluginPackageJson,
+  PublishablePluginPackageCandidate,
+} from "./plugin-publication-collector.ts";
+
+// Any change here can alter the package inventory for both registries. Range
+// selectors and workflow triggers must keep this closure in sync.
+export const PLUGIN_PUBLICATION_SHARED_AUTHORITY_PATHS = [
+  "package.json",
+  "pnpm-lock.yaml",
+  "packages/normalization-core/src",
+  "packages/plugin-package-contract/src",
+  "scripts/lib/npm-publish-plan.mjs",
+  "scripts/lib/plugin-publication-candidates.ts",
+  "scripts/lib/plugin-publication-collector.ts",
+  "scripts/lib/release-version.mjs",
+] as const;
+
+export const PLUGIN_NPM_RELEASE_AUTHORITY_PATHS = [
+  ...PLUGIN_PUBLICATION_SHARED_AUTHORITY_PATHS,
+  ".github/actions/setup-node-env",
+  ".github/workflows/plugin-npm-release.yml",
+  "scripts/generate-npm-package-lock.mjs",
+  "scripts/generate-npm-package-lock.mts",
+  "scripts/lib/actions-artifact-archive.mjs",
+  "scripts/lib/npm-json-output.mts",
+  "scripts/lib/plugin-npm-package-manifest.mjs",
+  "scripts/lib/plugin-npm-package-manifest.mts",
+  "scripts/lib/plugin-npm-release.ts",
+  "scripts/lib/tsx-cli-shim.mjs",
+  "scripts/plugin-npm-publish.sh",
+  "scripts/plugin-npm-release-check.ts",
+  "scripts/plugin-npm-release-plan.ts",
+  "scripts/plugin-publication-artifact.mjs",
+  "scripts/release-tooling-identity.d.mts",
+  "scripts/release-tooling-identity.mjs",
+  "scripts/verify-plugin-npm-published-runtime.mts",
+] as const;
+
+function hasAuthorityPathChanges(
+  paths: readonly string[],
+  authorityPaths: readonly string[],
+): boolean {
+  return paths.some((path) =>
+    authorityPaths.some(
+      (authorityPath) => path === authorityPath || path.startsWith(`${authorityPath}/`),
+    ),
+  );
+}
+
+export function hasPluginPublicationSharedAuthorityChanges(paths: readonly string[]): boolean {
+  return hasAuthorityPathChanges(paths, PLUGIN_PUBLICATION_SHARED_AUTHORITY_PATHS);
+}
+
+export function hasPluginNpmReleaseAuthorityChanges(paths: readonly string[]): boolean {
+  return hasAuthorityPathChanges(paths, PLUGIN_NPM_RELEASE_AUTHORITY_PATHS);
+}
+
+function readPluginPackageJson(absolutePath: string, repoPath: string): PluginPackageJson {
+  let raw: string;
+  try {
+    raw = readFileSync(absolutePath, "utf8");
+  } catch (error) {
+    throw new Error(`plugin candidate manifest is unreadable: ${repoPath}`, { cause: error });
+  }
+  try {
+    return JSON.parse(raw) as PluginPackageJson;
+  } catch (error) {
+    throw new Error(`plugin candidate manifest is malformed JSON: ${repoPath}`, { cause: error });
+  }
+}
+
+function pluginPackageJsonExists(absolutePath: string, repoPath: string): boolean {
+  try {
+    statSync(absolutePath);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return false;
+    }
+    throw new Error(`plugin candidate manifest is unreadable: ${repoPath}`, { cause: error });
+  }
+}
+
+function readOptionalPluginReadme(absolutePath: string, repoPath: string): string | undefined {
+  try {
+    return readFileSync(absolutePath, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return undefined;
+    }
+    throw new Error(`plugin candidate README is unreadable: ${repoPath}`, { cause: error });
+  }
+}
+
+export function collectExtensionPackageJsonCandidates<
+  TPackageJson extends PluginPackageJson = PluginPackageJson,
+>(rootDir = resolve(".")): PublishablePluginPackageCandidate<TPackageJson>[] {
+  const extensionsDir = join(rootDir, "extensions");
+  return readdirSync(extensionsDir, { withFileTypes: true }).flatMap((entry) => {
+    if (!entry.isDirectory()) {
+      return [];
+    }
+    const packageDir = `extensions/${entry.name}`;
+    const absolutePackageDir = join(extensionsDir, entry.name);
+    const packageJsonPath = join(absolutePackageDir, "package.json");
+    if (!pluginPackageJsonExists(packageJsonPath, `${packageDir}/package.json`)) {
+      return [];
+    }
+    return [
+      {
+        extensionId: entry.name,
+        packageDir,
+        packageJson: readPluginPackageJson(
+          packageJsonPath,
+          `${packageDir}/package.json`,
+        ) as TPackageJson,
+        readmeText: readOptionalPluginReadme(
+          join(absolutePackageDir, "README.md"),
+          `${packageDir}/README.md`,
+        ),
+      },
+    ];
+  });
+}
diff --git a/scripts/lib/plugin-publication-collector.ts b/scripts/lib/plugin-publication-collector.ts
new file mode 100644
index 000000000000..5f1fa15a76e5
--- /dev/null
+++ b/scripts/lib/plugin-publication-collector.ts
@@ -0,0 +1,369 @@
+import { normalizeOptionalString } from "../../packages/normalization-core/src/string-coerce.js";
+import { validateExternalCodePluginPackageJson } from "../../packages/plugin-package-contract/src/index.ts";
+import { resolveNpmPublishPlan } from "./npm-publish-plan.mjs";
+import { parseReleaseVersion } from "./release-version.mjs";
+
+export type PluginPackageJson = {
+  name?: string;
+  version?: string;
+  type?: string;
+  private?: boolean;
+  dependencies?: Record<string, unknown>;
+  optionalDependencies?: Record<string, unknown>;
+  repository?:
+    | string
+    | {
+        type?: string;
+        url?: string;
+      };
+  openclaw?: {
+    extensions?: string[];
+    install?: {
+      defaultChoice?: string;
+      minHostVersion?: string;
+      npmSpec?: string;
+    };
+    compat?: {
+      pluginApi?: string;
+      minGatewayVersion?: string;
+    };
+    build?: {
+      bundledDist?: boolean;
+      openclawVersion?: string;
+      pluginSdkVersion?: string;
+    };
+    release?: {
+      publishToClawHub?: boolean;
+      publishToNpm?: boolean;
+      requireLatestDependencies?: unknown;
+    };
+  };
+};
+
+export type PublishablePluginPackageCandidate<
+  TPackageJson extends PluginPackageJson = PluginPackageJson,
+> = {
+  extensionId: string;
+  packageDir: string;
+  packageJson: TPackageJson;
+  readmeText?: string;
+};
+
+type RequiredLatestDependency = {
+  packageName: string;
+  version: string;
+};
+
+export type PublishablePluginPackage = {
+  extensionId: string;
+  packageDir: string;
+  packageName: string;
+  version: string;
+  channel: "stable" | "alpha" | "beta";
+  publishTag: "latest" | "alpha" | "beta" | "extended-stable";
+  installNpmSpec?: string;
+  requiredLatestDependencies?: RequiredLatestDependency[];
+};
+
+export type PublishablePluginPackageFilters = {
+  extensionIds?: readonly string[];
+  packageNames?: readonly string[];
+  npmDistTag?: "extended-stable";
+  rootVersion?: string;
+};
+
+type PublishablePluginPackageSource = Pick<
+  PublishablePluginPackage,
+  "extensionId" | "packageDir" | "packageName"
+>;
+
+export const OPENCLAW_PLUGIN_NPM_REPOSITORY_URL = "https://github.com/openclaw/openclaw";
+const SAFE_CLAWHUB_EXTENSION_ID = /^[a-z0-9][a-z0-9._-]*$/;
+
+/** Explicit core ownership defers staged external publication until the plugin is externalized. */
+function isPluginExternalPublicationDeferred(packageJson: {
+  openclaw?: { build?: { bundledDist?: unknown } };
+}): boolean {
+  return packageJson.openclaw?.build?.bundledDist === true;
+}
+
+function collectRequiredLatestDependencies(packageJson: PluginPackageJson): {
+  dependencies: RequiredLatestDependency[];
+  errors: string[];
+} {
+  const configured = packageJson.openclaw?.release?.requireLatestDependencies;
+  if (configured === undefined) {
+    return { dependencies: [], errors: [] };
+  }
+  if (!Array.isArray(configured)) {
+    return {
+      dependencies: [],
+      errors: ["openclaw.release.requireLatestDependencies must be an array of package names."],
+    };
+  }
+
+  const runtimeDependencies = {
+    ...packageJson.dependencies,
+    ...packageJson.optionalDependencies,
+  };
+  const dependencies: RequiredLatestDependency[] = [];
+  const errors: string[] = [];
+  const seen = new Set<string>();
+
+  for (const value of configured) {
+    if (typeof value !== "string" || !value.trim()) {
+      errors.push(
+        "openclaw.release.requireLatestDependencies must contain only non-empty package names.",
+      );
+      continue;
+    }
+    const packageName = value.trim();
+    if (seen.has(packageName)) {
+      errors.push(
+        `openclaw.release.requireLatestDependencies must not contain duplicate package names; found "${packageName}".`,
+      );
+      continue;
+    }
+    seen.add(packageName);
+
+    const version = runtimeDependencies[packageName];
+    if (typeof version !== "string" || !version.trim()) {
+      errors.push(
+        `openclaw.release.requireLatestDependencies must reference package.json dependencies or optionalDependencies; "${packageName}" is not a runtime dependency.`,
+      );
+      continue;
+    }
+    dependencies.push({ packageName, version: version.trim() });
+  }
+
+  return { dependencies, errors };
+}
+
+function resolvePublishablePluginVersion(params: {
+  extensionId: string;
+  packageJson: Pick<PluginPackageJson, "version">;
+  validationErrors: string[];
+}): { version: string; parsedVersion: NonNullable<ReturnType<typeof parseReleaseVersion>> } | null {
+  const version = params.packageJson.version?.trim() ?? "";
+  const parsedVersion = parseReleaseVersion(version);
+  if (parsedVersion === null) {
+    params.validationErrors.push(
+      `${params.extensionId}: package.json version must match YYYY.M.PATCH, YYYY.M.PATCH-N, YYYY.M.PATCH-alpha.N, or YYYY.M.PATCH-beta.N; found "${version}".`,
+    );
+    return null;
+  }
+  return { version, parsedVersion };
+}
+
+export function collectPublishablePluginPackageErrors(
+  candidate: PublishablePluginPackageCandidate,
+): string[] {
+  const { packageJson } = candidate;
+  const errors: string[] = [];
+  const packageName = packageJson.name?.trim() ?? "";
+  const packageVersion = packageJson.version?.trim() ?? "";
+  const installNpmSpec = normalizeOptionalString(packageJson.openclaw?.install?.npmSpec);
+  const repositoryUrl =
+    typeof packageJson.repository === "string"
+      ? packageJson.repository.trim()
+      : (packageJson.repository?.url?.trim() ?? "");
+  const extensions = packageJson.openclaw?.extensions ?? [];
+  const requiredLatestDependencies = collectRequiredLatestDependencies(packageJson);
+
+  if (!packageName.startsWith("@openclaw/")) {
+    errors.push(
+      `package name must start with "@openclaw/"; found "${packageName || "<missing>"}".`,
+    );
+  }
+  if (packageJson.private === true) {
+    errors.push("package.json private must not be true.");
+  }
+  if (packageJson.type !== "module") {
+    errors.push('package.json type must be "module" so built .js runtime entries load as ESM.');
+  }
+  if (!candidate.readmeText?.trim()) {
+    errors.push("README.md must exist and contain package documentation.");
+  }
+  if (repositoryUrl !== OPENCLAW_PLUGIN_NPM_REPOSITORY_URL) {
+    errors.push(
+      `package.json repository.url must be "${OPENCLAW_PLUGIN_NPM_REPOSITORY_URL}" so npm provenance can validate GitHub trusted publishing; found "${repositoryUrl || "<missing>"}".`,
+    );
+  }
+  if (!packageVersion) {
+    errors.push("package.json version must be non-empty.");
+  } else if (parseReleaseVersion(packageVersion) === null) {
+    errors.push(
+      `package.json version must match YYYY.M.PATCH, YYYY.M.PATCH-N, YYYY.M.PATCH-alpha.N, or YYYY.M.PATCH-beta.N; found "${packageVersion}".`,
+    );
+  }
+  if (!Array.isArray(extensions) || extensions.length === 0) {
+    errors.push("openclaw.extensions must contain at least one entry.");
+  }
+  if (extensions.some((entry) => typeof entry !== "string" || !entry.trim())) {
+    errors.push("openclaw.extensions must contain only non-empty strings.");
+  }
+  if (!installNpmSpec) {
+    errors.push("openclaw.install.npmSpec must be a non-empty string for publishable plugins.");
+  }
+  errors.push(...requiredLatestDependencies.errors);
+  errors.push(
+    ...validateExternalCodePluginPackageJson(packageJson).issues.map((issue) => issue.message),
+  );
+
+  return errors;
+}
+
+function collectConflictingPluginPackageSourceErrors(
+  sources: readonly PublishablePluginPackageSource[],
+): string[] {
+  const sourcesByPackageName = new Map<string, Map<string, PublishablePluginPackageSource>>();
+  for (const source of sources) {
+    const packageName = source.packageName.trim();
+    if (!packageName) {
+      continue;
+    }
+    const packageSources = sourcesByPackageName.get(packageName) ?? new Map();
+    packageSources.set(`${source.extensionId}\0${source.packageDir}`, source);
+    sourcesByPackageName.set(packageName, packageSources);
+  }
+
+  return [...sourcesByPackageName.entries()]
+    .flatMap(([packageName, packageSources]) => {
+      if (packageSources.size < 2) {
+        return [];
+      }
+      const descriptions = [...packageSources.values()]
+        .map((source) => `${source.extensionId} (${source.packageDir})`)
+        .toSorted();
+      return [
+        `package ${packageName} is declared by multiple plugin sources: ${descriptions.join(", ")}.`,
+      ];
+    })
+    .toSorted();
+}
+
+export function assertUniquePublishablePluginPackageSources(
+  sources: readonly PublishablePluginPackageSource[],
+  label: string,
+): void {
+  const errors = collectConflictingPluginPackageSourceErrors(sources);
+  if (errors.length === 0) {
+    return;
+  }
+  throw new Error(`${label} has conflicting plugin package provenance:\n${errors.join("\n")}`);
+}
+
+export function collectPublishablePluginPackagesFromCandidates(
+  candidates: readonly PublishablePluginPackageCandidate[],
+  target: "npm" | "clawhub",
+  filters: PublishablePluginPackageFilters = {},
+): PublishablePluginPackage[] {
+  const publishable: PublishablePluginPackage[] = [];
+  const validationErrors: string[] = [];
+  const selectedExtensionIds = new Set(filters.extensionIds ?? []);
+  const selectedPackageNames = new Set(filters.packageNames ?? []);
+  const hasSelectedExtensionIds = Array.isArray(filters.extensionIds);
+  const hasSelectedPackageNames = Array.isArray(filters.packageNames);
+
+  validationErrors.push(
+    ...collectConflictingPluginPackageSourceErrors(
+      candidates
+        .filter(
+          (candidate) =>
+            !isPluginExternalPublicationDeferred(candidate.packageJson) &&
+            (candidate.packageJson.openclaw?.release?.publishToNpm === true ||
+              candidate.packageJson.openclaw?.release?.publishToClawHub === true),
+        )
+        .map((candidate) => ({
+          extensionId: candidate.extensionId,
+          packageDir: candidate.packageDir,
+          packageName: candidate.packageJson.name?.trim() ?? "",
+        })),
+    ),
+  );
+
+  for (const candidate of candidates) {
+    const { extensionId, packageDir, packageJson } = candidate;
+    if (hasSelectedExtensionIds && !selectedExtensionIds.has(extensionId)) {
+      continue;
+    }
+    const packageName = packageJson.name?.trim() ?? "";
+    if (hasSelectedPackageNames && !selectedPackageNames.has(packageName)) {
+      continue;
+    }
+    if (isPluginExternalPublicationDeferred(packageJson)) {
+      continue;
+    }
+    const enabled =
+      target === "npm"
+        ? packageJson.openclaw?.release?.publishToNpm === true
+        : packageJson.openclaw?.release?.publishToClawHub === true;
+    if (!enabled) {
+      continue;
+    }
+    if (target === "clawhub" && !SAFE_CLAWHUB_EXTENSION_ID.test(extensionId)) {
+      validationErrors.push(
+        `${extensionId}: extension directory name must match ^[a-z0-9][a-z0-9._-]*$ for ClawHub publish.`,
+      );
+      continue;
+    }
+
+    const errors = collectPublishablePluginPackageErrors(candidate);
+    if (errors.length > 0) {
+      validationErrors.push(...errors.map((error) => `${extensionId}: ${error}`));
+      continue;
+    }
+    const resolvedVersion = resolvePublishablePluginVersion({
+      extensionId,
+      packageJson,
+      validationErrors,
+    });
+    if (!resolvedVersion) {
+      continue;
+    }
+    const { version, parsedVersion } = resolvedVersion;
+    const requiredLatestDependencies = collectRequiredLatestDependencies(packageJson).dependencies;
+    const publishTag =
+      target === "npm"
+        ? resolveNpmPublishPlan(version, undefined, filters.npmDistTag).publishTag
+        : parsedVersion.channel === "alpha"
+          ? "alpha"
+          : parsedVersion.channel === "beta"
+            ? "beta"
+            : "latest";
+
+    publishable.push({
+      extensionId,
+      packageDir,
+      packageName,
+      version,
+      channel: parsedVersion.channel,
+      publishTag,
+      ...(target === "npm"
+        ? { installNpmSpec: normalizeOptionalString(packageJson.openclaw?.install?.npmSpec) }
+        : {}),
+      ...(requiredLatestDependencies.length > 0 ? { requiredLatestDependencies } : {}),
+    });
+  }
+
+  if (target === "npm" && filters.npmDistTag === "extended-stable") {
+    const rootVersion = filters.rootVersion?.trim() ?? "";
+    for (const plugin of publishable) {
+      if (plugin.version !== rootVersion) {
+        validationErrors.push(
+          `${plugin.extensionId}: package version ${plugin.version} must match root package version ${rootVersion || "<missing>"} for extended-stable publication.`,
+        );
+      }
+    }
+  }
+
+  if (validationErrors.length > 0) {
+    const label =
+      target === "clawhub"
+        ? "Publishable ClawHub plugin metadata validation failed"
+        : "Publishable plugin metadata validation failed";
+    throw new Error(`${label}:\n${validationErrors.map((error) => `- ${error}`).join("\n")}`);
+  }
+
+  return publishable.toSorted((left, right) => left.packageName.localeCompare(right.packageName));
+}
diff --git a/scripts/plugin-npm-release-check.ts b/scripts/plugin-npm-release-check.ts
index ef9cc39abf64..5ed00f3adc9d 100644
--- a/scripts/plugin-npm-release-check.ts
+++ b/scripts/plugin-npm-release-check.ts
@@ -5,7 +5,7 @@ import { pathToFileURL } from "node:url";
 import {
   assertPluginReleaseDependencyFreshness,
   assertPluginReleaseVersionFloors,
-  collectChangedExtensionIdsFromGitRange,
+  collectPluginNpmGitRangeSelection,
   collectPublishablePluginPackages,
   parsePluginNpmReleaseArgs,
   resolveChangedPublishablePluginPackages,
@@ -15,17 +15,19 @@ import {
 function runPluginNpmReleaseCheck(argv: string[]) {
   const { selection, selectionMode, npmDistTag, baseRef, headRef } =
     parsePluginNpmReleaseArgs(argv);
-  const changedExtensionIds =
+  const gitRangeSelection =
     baseRef && headRef
-      ? collectChangedExtensionIdsFromGitRange({
+      ? collectPluginNpmGitRangeSelection({
           gitRange: { baseRef, headRef },
         })
-      : [];
+      : undefined;
   const publishable = collectPublishablePluginPackages(".", {
     extensionIds:
-      selectionMode === "all-publishable" || !(baseRef && headRef)
+      selectionMode === "all-publishable" ||
+      !gitRangeSelection ||
+      gitRangeSelection.authorityChanged
         ? undefined
-        : changedExtensionIds,
+        : gitRangeSelection.changedExtensionIds,
     packageNames: selection.length > 0 ? selection : undefined,
     npmDistTag,
   });
@@ -37,11 +39,13 @@ function runPluginNpmReleaseCheck(argv: string[]) {
             plugins: publishable,
             selection,
           })
-        : baseRef && headRef
-          ? resolveChangedPublishablePluginPackages({
-              plugins: publishable,
-              changedExtensionIds,
-            })
+        : gitRangeSelection
+          ? gitRangeSelection.authorityChanged
+            ? publishable
+            : resolveChangedPublishablePluginPackages({
+                plugins: publishable,
+                changedExtensionIds: gitRangeSelection.changedExtensionIds,
+              })
           : publishable;
 
   if (selectionMode !== undefined || selection.length > 0) {
diff --git a/scripts/release-plan-contract.d.mts b/scripts/release-plan-contract.d.mts
new file mode 100644
index 000000000000..86b0e9148ec3
--- /dev/null
+++ b/scripts/release-plan-contract.d.mts
@@ -0,0 +1,47 @@
+import type {
+  ReleaseValidationIntent,
+  ReleaseValidationProfile,
+  ReleaseValidationPurpose,
+} from "./release-validation-intent.mjs";
+
+export type ReleasePlanPurpose = ReleaseValidationPurpose;
+
+export type ReleasePlan = {
+  schema: "openclaw.release-plan.v1";
+  release_id: string;
+  version: string;
+  tag: string | null;
+  candidate_sha: string;
+  target_context_ref: string;
+  purpose: ReleasePlanPurpose;
+  tooling: {
+    repository: "openclaw/openclaw";
+    workflow_path: ".github/workflows/full-release-validation.yml";
+    ref: string;
+    sha: string;
+  };
+  validation: {
+    intent: ReleaseValidationIntent;
+    profile: ReleaseValidationProfile;
+    soak: boolean;
+    allowed_groups: string[];
+  };
+  inventory: {
+    packages: Array<{ name: string; version: string; targets: Array<"clawhub" | "npm"> }>;
+    platforms: Array<{ id: string; source: string }>;
+  };
+};
+
+export type ReleasePlanLock = {
+  schema: "openclaw.release-plan-lock.v1";
+  digest: string;
+  plan: ReleasePlan;
+};
+
+export const RELEASE_PLAN_SCHEMA: "openclaw.release-plan.v1";
+export const RELEASE_PLAN_CANONICALIZATION: "ascii-sorted-compact-json-trailing-newline-v1";
+export function validateReleasePlan(value: unknown): ReleasePlan;
+export function canonicalReleasePlanJson(value: unknown): string;
+export function createReleasePlanLock(value: unknown): ReleasePlanLock;
+export function canonicalReleasePlanLockJson(value: unknown): string;
+export function parseReleasePlanLockJson(text: string): ReleasePlanLock;
diff --git a/scripts/release-plan-contract.mjs b/scripts/release-plan-contract.mjs
new file mode 100644
index 000000000000..3a83044633ef
--- /dev/null
+++ b/scripts/release-plan-contract.mjs
@@ -0,0 +1,442 @@
+import { createHash } from "node:crypto";
+import { isRecord } from "./lib/record-shared.mjs";
+import { parseReleaseVersion } from "./lib/release-version.mjs";
+import {
+  releaseValidationIntentForPurpose,
+  resolveReleaseValidationIntent,
+} from "./release-validation-intent.mjs";
+
+export const RELEASE_PLAN_SCHEMA = "openclaw.release-plan.v1";
+const RELEASE_PLAN_LOCK_SCHEMA = "openclaw.release-plan-lock.v1";
+export const RELEASE_PLAN_CANONICALIZATION = "ascii-sorted-compact-json-trailing-newline-v1";
+const RELEASE_PLAN_MAX_BYTES = 32 * 1024;
+
+const SHA_PATTERN = /^[a-f0-9]{40}$/u;
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+const ASCII_PATTERN = /^[\x20-\x7e]+$/u;
+const REPOSITORY = "openclaw/openclaw";
+const WORKFLOW_PATH = ".github/workflows/full-release-validation.yml";
+const PACKAGE_TARGETS = new Set(["clawhub", "npm"]);
+const compareAscii = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function exactKeys(value, keys, label) {
+  const actual = Object.keys(value).toSorted(compareAscii);
+  const expected = [...keys].toSorted(compareAscii);
+  if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+    fail(`${label} keys must be exactly: ${expected.join(", ")}`);
+  }
+}
+
+function asciiString(value, label) {
+  if (typeof value !== "string" || !ASCII_PATTERN.test(value)) {
+    fail(`${label} must be a non-empty printable ASCII string`);
+  }
+  return value;
+}
+
+function sha(value, label) {
+  const normalized = asciiString(value, label);
+  if (!SHA_PATTERN.test(normalized)) {
+    fail(`${label} must be a lowercase 40-character commit SHA`);
+  }
+  return normalized;
+}
+
+function digest(value, label) {
+  if (typeof value !== "string" || !DIGEST_PATTERN.test(value)) {
+    fail(`${label} must be sha256:<64 lowercase hex characters>`);
+  }
+  return value;
+}
+
+function sortedUniqueStrings(value, label) {
+  if (!Array.isArray(value) || value.length === 0) {
+    fail(`${label} must be a non-empty array`);
+  }
+  const result = value.map((entry, index) => asciiString(entry, `${label}[${index}]`));
+  if (
+    new Set(result).size !== result.length ||
+    result.some((entry, index) => index > 0 && compareAscii(result[index - 1], entry) >= 0)
+  ) {
+    fail(`${label} must contain unique strings in ascending ASCII order`);
+  }
+  return result;
+}
+
+function sortedUniqueEnumStrings(value, allowed, label) {
+  const result = sortedUniqueStrings(value, label);
+  const unsupported = result.find((entry) => !allowed.has(entry));
+  if (unsupported) {
+    fail(`${label} contains unsupported value: ${unsupported}`);
+  }
+  return result;
+}
+
+function canonicalPath(parent, key) {
+  return `${parent}[${JSON.stringify(key)}]`;
+}
+
+function canonicalize(value, path = "$", ancestors = new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      fail(`canonical JSON number at ${path} must be finite`);
+    }
+    if (Object.is(value, -0)) {
+      fail(`canonical JSON number at ${path} must not be negative zero`);
+    }
+    return value;
+  }
+  if (typeof value !== "object") {
+    fail(`canonical JSON contains unsupported ${typeof value} at ${path}`);
+  }
+  if (ancestors.has(value)) {
+    fail(`canonical JSON must not contain cycles at ${path}`);
+  }
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const keys = Reflect.ownKeys(value).filter((key) => key !== "length");
+      if (
+        keys.length !== value.length ||
+        keys.some((key, index) => typeof key !== "string" || key !== String(index))
+      ) {
+        fail(`canonical JSON array at ${path} must be dense and contain no extra properties`);
+      }
+      return keys.map((key) => {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor?.enumerable || !("value" in descriptor)) {
+          fail(`canonical JSON array at ${path} must contain enumerable data properties only`);
+        }
+        return canonicalize(descriptor.value, canonicalPath(path, key), ancestors);
+      });
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      fail(`canonical JSON object at ${path} must be plain`);
+    }
+    const keys = Reflect.ownKeys(value);
+    if (keys.some((key) => typeof key !== "string")) {
+      fail(`canonical JSON object at ${path} must use string keys only`);
+    }
+    return Object.fromEntries(
+      keys.toSorted(compareAscii).map((key) => {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor?.enumerable || !("value" in descriptor)) {
+          fail(`canonical JSON object at ${path} must contain enumerable data properties only`);
+        }
+        return [key, canonicalize(descriptor.value, canonicalPath(path, key), ancestors)];
+      }),
+    );
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function canonicalAsciiJson(value) {
+  const json = `${JSON.stringify(canonicalize(value))}\n`;
+  if (!/^[\x20-\x7e]+\n$/u.test(json)) {
+    fail("canonical JSON must be printable ASCII with exactly one trailing newline");
+  }
+  return json;
+}
+
+function assertNoDuplicateJsonKeys(text) {
+  const tokenPattern = new RegExp(
+    String.raw`"(?:\\(?:["\\/bfnrt]|u[a-fA-F0-9]{4})|[^"\\\u0000-\u001f])*"|[{}\[\],:]|true|false|null|-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?|\s+`,
+    "guy",
+  );
+  const stack = [];
+  for (let index = 0; index < text.length;) {
+    tokenPattern.lastIndex = index;
+    const match = tokenPattern.exec(text);
+    if (!match) {
+      fail("release plan lock JSON is invalid JSON");
+    }
+    index = tokenPattern.lastIndex;
+    const token = match[0];
+    if (/^\s+$/u.test(token)) {
+      continue;
+    }
+    const current = stack.at(-1);
+    if (token === "{") {
+      stack.push({ keys: new Set(), expectingKey: true });
+    } else if (token === "[") {
+      stack.push(null);
+    } else if (token === "}" || token === "]") {
+      stack.pop();
+    } else if (token === "," && current !== null && current !== undefined) {
+      current.expectingKey = true;
+    } else if (token === ":" && current !== null && current !== undefined) {
+      current.expectingKey = false;
+    } else if (token.startsWith('"') && current?.expectingKey) {
+      const key = JSON.parse(token);
+      if (current.keys.has(key)) {
+        fail("release plan JSON contains a duplicate key");
+      }
+      current.keys.add(key);
+      current.expectingKey = false;
+    }
+  }
+}
+
+function validatePackages(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    fail("release plan packages must be a non-empty array");
+  }
+  const packages = value.map((entry, index) => {
+    if (!isRecord(entry)) {
+      fail(`release plan packages[${index}] must be an object`);
+    }
+    exactKeys(entry, ["name", "version", "targets"], `release plan packages[${index}]`);
+    return {
+      name: asciiString(entry.name, `release plan packages[${index}].name`),
+      version: asciiString(entry.version, `release plan packages[${index}].version`),
+      targets: sortedUniqueEnumStrings(
+        entry.targets,
+        PACKAGE_TARGETS,
+        `release plan packages[${index}].targets`,
+      ),
+    };
+  });
+  const names = packages.map((entry) => entry.name);
+  if (
+    new Set(names).size !== names.length ||
+    names.some((entry, index) => index > 0 && compareAscii(names[index - 1], entry) >= 0)
+  ) {
+    fail("release plan packages must have unique names in ascending ASCII order");
+  }
+  return packages;
+}
+
+function validatePlatforms(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    fail("release plan platforms must be a non-empty array");
+  }
+  const platforms = value.map((entry, index) => {
+    if (!isRecord(entry)) {
+      fail(`release plan platforms[${index}] must be an object`);
+    }
+    exactKeys(entry, ["id", "source"], `release plan platforms[${index}]`);
+    return {
+      id: asciiString(entry.id, `release plan platforms[${index}].id`),
+      source: asciiString(entry.source, `release plan platforms[${index}].source`),
+    };
+  });
+  const ids = platforms.map((entry) => entry.id);
+  if (
+    new Set(ids).size !== ids.length ||
+    ids.some((entry, index) => index > 0 && compareAscii(ids[index - 1], entry) >= 0)
+  ) {
+    fail("release plan platforms must have unique ids in ascending ASCII order");
+  }
+  return platforms;
+}
+
+function validatePurposeMatrix({ candidateSha, purpose, tag, targetContextRef, version }) {
+  const parsedVersion = parseReleaseVersion(version);
+  if (parsedVersion === null || parsedVersion.version !== version) {
+    fail("release plan version must use a supported release version");
+  }
+  if (purpose === "beta-publish" && parsedVersion.channel === "stable") {
+    fail("beta-publish release plan version must be alpha or beta");
+  }
+  if (purpose === "stable-publish" && parsedVersion.channel !== "stable") {
+    fail("stable-publish release plan version must be stable");
+  }
+  if (purpose === "diagnostic" || purpose === "main-qualification") {
+    if (tag !== null || targetContextRef !== candidateSha) {
+      fail(`${purpose} release plans require a null tag and candidate SHA context`);
+    }
+    return;
+  }
+  const expectedTag = `v${version}`;
+  if (tag !== expectedTag || targetContextRef !== `refs/tags/${expectedTag}`) {
+    fail(`${purpose} release plans require the exact version tag context`);
+  }
+}
+
+function validateToolingRoute(purpose, ref, toolingSha) {
+  const protectedMatch = /^refs\/tags\/release-publish\/([a-f0-9]{12})-[1-9][0-9]*$/u.exec(ref);
+  const protectedRoute = protectedMatch?.[1] === toolingSha.slice(0, 12);
+  if (purpose === "diagnostic" || purpose === "main-qualification") {
+    if (ref !== "refs/heads/main" && !protectedRoute) {
+      fail(`${purpose} tooling must use trusted main or a protected release-publish tag`);
+    }
+    return;
+  }
+  if (!protectedRoute) {
+    fail(`${purpose} tooling must use a protected release-publish tag bound to its SHA`);
+  }
+}
+
+export function validateReleasePlan(value) {
+  canonicalize(value);
+  if (!isRecord(value)) {
+    fail("release plan must be an object");
+  }
+  exactKeys(
+    value,
+    [
+      "schema",
+      "release_id",
+      "version",
+      "tag",
+      "candidate_sha",
+      "target_context_ref",
+      "purpose",
+      "tooling",
+      "validation",
+      "inventory",
+    ],
+    "release plan",
+  );
+  if (value.schema !== RELEASE_PLAN_SCHEMA) {
+    fail(`release plan schema must be ${RELEASE_PLAN_SCHEMA}`);
+  }
+  const purpose = asciiString(value.purpose, "release plan purpose");
+  const version = asciiString(value.version, "release plan version");
+  const releaseId = asciiString(value.release_id, "release plan release_id");
+  if (releaseId !== version) {
+    fail("release plan release_id must equal version");
+  }
+  const tag = value.tag === null ? null : asciiString(value.tag, "release plan tag");
+  const candidateSha = sha(value.candidate_sha, "release plan candidate SHA");
+  const targetContextRef = asciiString(value.target_context_ref, "release plan target_context_ref");
+  validatePurposeMatrix({ candidateSha, purpose, tag, targetContextRef, version });
+
+  if (!isRecord(value.tooling)) {
+    fail("release plan tooling must be an object");
+  }
+  exactKeys(value.tooling, ["repository", "workflow_path", "ref", "sha"], "release plan tooling");
+  const toolingRef = asciiString(value.tooling.ref, "release plan tooling ref");
+  if (!/^refs\/(?:heads|tags)\/[A-Za-z0-9._/-]+$/u.test(toolingRef)) {
+    fail("release plan tooling ref must be a qualified branch or tag ref");
+  }
+  if (!isRecord(value.validation)) {
+    fail("release plan validation must be an object");
+  }
+  exactKeys(
+    value.validation,
+    ["intent", "profile", "soak", "allowed_groups"],
+    "release plan validation",
+  );
+  const intent = asciiString(value.validation.intent, "release plan validation intent");
+  releaseValidationIntentForPurpose(purpose, intent);
+  const profile = asciiString(value.validation.profile, "release plan validation profile");
+  if (typeof value.validation.soak !== "boolean") {
+    fail("release plan validation soak must be boolean");
+  }
+  const validationPolicy = resolveReleaseValidationIntent(intent, {
+    profile,
+    soak: value.validation.soak,
+  });
+  if (!isRecord(value.inventory)) {
+    fail("release plan inventory must be an object");
+  }
+  exactKeys(value.inventory, ["packages", "platforms"], "release plan inventory");
+  const plan = {
+    schema: RELEASE_PLAN_SCHEMA,
+    release_id: releaseId,
+    version,
+    tag,
+    candidate_sha: candidateSha,
+    target_context_ref: targetContextRef,
+    purpose,
+    tooling: {
+      repository: asciiString(value.tooling.repository, "release plan tooling repository"),
+      workflow_path: asciiString(value.tooling.workflow_path, "release plan tooling workflow_path"),
+      ref: toolingRef,
+      sha: sha(value.tooling.sha, "release plan tooling SHA"),
+    },
+    validation: {
+      intent: validationPolicy.intent,
+      profile: validationPolicy.profile,
+      soak: validationPolicy.soak,
+      allowed_groups: sortedUniqueStrings(
+        value.validation.allowed_groups,
+        "release plan validation allowed_groups",
+      ),
+    },
+    inventory: {
+      packages: validatePackages(value.inventory.packages),
+      platforms: validatePlatforms(value.inventory.platforms),
+    },
+  };
+  if (plan.tooling.repository !== REPOSITORY) {
+    fail(`release plan tooling repository must be ${REPOSITORY}`);
+  }
+  if (plan.tooling.workflow_path !== WORKFLOW_PATH) {
+    fail(`release plan tooling workflow_path must be ${WORKFLOW_PATH}`);
+  }
+  validateToolingRoute(plan.purpose, plan.tooling.ref, plan.tooling.sha);
+  if (Buffer.byteLength(canonicalAsciiJson(plan), "ascii") > RELEASE_PLAN_MAX_BYTES) {
+    fail(`release plan exceeds ${RELEASE_PLAN_MAX_BYTES} bytes`);
+  }
+  return plan;
+}
+
+export function canonicalReleasePlanJson(value) {
+  return canonicalAsciiJson(validateReleasePlan(value));
+}
+
+function releasePlanDigest(value) {
+  return `sha256:${createHash("sha256").update(canonicalReleasePlanJson(value), "ascii").digest("hex")}`;
+}
+
+export function createReleasePlanLock(value) {
+  const plan = validateReleasePlan(value);
+  return {
+    schema: RELEASE_PLAN_LOCK_SCHEMA,
+    digest: releasePlanDigest(plan),
+    plan,
+  };
+}
+
+function validateReleasePlanLock(value) {
+  canonicalize(value);
+  if (!isRecord(value)) {
+    fail("release plan lock must be an object");
+  }
+  exactKeys(value, ["schema", "digest", "plan"], "release plan lock");
+  if (value.schema !== RELEASE_PLAN_LOCK_SCHEMA) {
+    fail(`release plan lock schema must be ${RELEASE_PLAN_LOCK_SCHEMA}`);
+  }
+  const plan = validateReleasePlan(value.plan);
+  const planDigest = digest(value.digest, "release plan lock digest");
+  if (planDigest !== releasePlanDigest(plan)) {
+    fail("release plan lock digest does not match its canonical plan");
+  }
+  return { schema: RELEASE_PLAN_LOCK_SCHEMA, digest: planDigest, plan };
+}
+
+export function canonicalReleasePlanLockJson(value) {
+  return canonicalAsciiJson(validateReleasePlanLock(value));
+}
+
+export function parseReleasePlanLockJson(text) {
+  if (typeof text !== "string" || Buffer.byteLength(text, "utf8") > RELEASE_PLAN_MAX_BYTES + 4096) {
+    fail("release plan lock JSON is missing or too large");
+  }
+  if (!/^[\x20-\x7e]+\n$/u.test(text)) {
+    fail("release plan lock JSON must be compact printable ASCII with exactly one trailing LF");
+  }
+  assertNoDuplicateJsonKeys(text);
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new Error("release plan lock JSON is invalid JSON", { cause: error });
+  }
+  const lock = validateReleasePlanLock(value);
+  if (text !== canonicalReleasePlanLockJson(lock)) {
+    fail("release plan lock JSON does not use canonical bytes");
+  }
+  return lock;
+}
diff --git a/scripts/release-plan-producer-core.mts b/scripts/release-plan-producer-core.mts
new file mode 100644
index 000000000000..5c6062cec55a
--- /dev/null
+++ b/scripts/release-plan-producer-core.mts
@@ -0,0 +1,633 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { collectExtensionPackageJsonCandidates } from "./lib/plugin-publication-candidates.ts";
+import {
+  collectPublishablePluginPackagesFromCandidates,
+  type PluginPackageJson,
+} from "./lib/plugin-publication-collector.ts";
+import { parseReleaseVersion } from "./lib/release-version.mjs";
+import {
+  canonicalReleasePlanJson,
+  canonicalReleasePlanLockJson,
+  createReleasePlanLock,
+  parseReleasePlanLockJson,
+  RELEASE_PLAN_SCHEMA,
+  validateReleasePlan,
+  type ReleasePlan,
+  type ReleasePlanLock,
+  type ReleasePlanPurpose,
+} from "./release-plan-contract.mjs";
+import { verifyReleaseToolingIdentity } from "./release-tooling-identity.mjs";
+import {
+  releaseValidationIntentForPurpose,
+  resolveReleaseValidationIntent,
+  type ReleaseValidationIntent,
+} from "./release-validation-intent.mjs";
+
+type ReleasePlanIntent = "publish" | "diagnostic" | "postpublish-confidence" | "main-qualification";
+type MainQualificationValidationIntent = Extract<
+  ReleaseValidationIntent,
+  "main-daily" | "main-weekly"
+>;
+
+type ReleasePlanSource = {
+  repoRoot?: string;
+  candidateSha: string;
+  candidateRef: string;
+  toolingSha: string;
+  toolingFullRef: string;
+  runGh?: (args: string[]) => string;
+  intent: ReleasePlanIntent;
+  validationIntent?: MainQualificationValidationIntent;
+};
+
+type CorePackagePolicy = {
+  path: string;
+  dependency?: string;
+};
+
+type ReleasePlanRuntime = {
+  parseYamlDocuments: (sources: [string, string, string]) => [unknown, unknown, unknown];
+  runGh: (args: string[]) => string;
+};
+
+type ReleasePlanProducerRequest =
+  | { operation: "produce" | "produce-lock"; params: ReleasePlanSource }
+  | { operation: "verify-lock"; lockJson: string; params: ReleasePlanSource };
+
+const REPOSITORY = "openclaw/openclaw";
+const VALIDATION_WORKFLOW_PATH = ".github/workflows/full-release-validation.yml";
+const PUBLICATION_WORKFLOW_PATH = ".github/workflows/openclaw-release-publish.yml";
+const NPM_PUBLICATION_WORKFLOW_PATH = ".github/workflows/openclaw-npm-release.yml";
+const YAML_PACKAGE_VERSION = "2.9.0";
+const YAML_PACKAGE_INTEGRITY =
+  "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==";
+const compareAscii = (left: string, right: string) => (left < right ? -1 : left > right ? 1 : 0);
+function git(repoRoot: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd: repoRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+function resolveCommit(repoRoot: string, revision: string, label: string): string {
+  let resolved: string;
+  try {
+    resolved = git(repoRoot, ["rev-parse", "--verify", `${revision}^{commit}`]);
+  } catch {
+    throw new Error(`${label} does not resolve to a commit: ${revision}`);
+  }
+  if (!/^[a-f0-9]{40}$/u.test(resolved)) {
+    throw new Error(`${label} did not resolve to an exact lowercase commit SHA`);
+  }
+  return resolved;
+}
+function requireExactSha(value: string, label: string): string {
+  if (!/^[a-f0-9]{40}$/u.test(value)) {
+    throw new Error(`${label} must be an exact lowercase 40-character commit SHA`);
+  }
+  return value;
+}
+function requireQualifiedRef(value: string, label: string): string {
+  if (!/^refs\/(?:heads|tags)\/[A-Za-z0-9._/-]+$/u.test(value)) {
+    throw new Error(`${label} must be a qualified branch or tag ref`);
+  }
+  return value;
+}
+
+function readGitBytes(repoRoot: string, commit: string, path: string): Buffer {
+  try {
+    return execFileSync("git", ["show", `${commit}:${path}`], {
+      cwd: repoRoot,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+  } catch {
+    throw new Error(`${path} is missing from ${commit}`);
+  }
+}
+
+function readGitText(repoRoot: string, commit: string, path: string): string {
+  return readGitBytes(repoRoot, commit, path).toString("utf8");
+}
+function gitPathExists(repoRoot: string, commit: string, path: string): boolean {
+  try {
+    execFileSync("git", ["cat-file", "-e", `${commit}:${path}`], {
+      cwd: repoRoot,
+      stdio: "ignore",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+type LineRange = { start: number; end: number };
+
+function findLockfileMapping(
+  lines: string[],
+  key: string,
+  indent: number,
+  scope: LineRange = { start: 0, end: lines.length },
+): LineRange {
+  const declaration = `${" ".repeat(indent)}${key}:`;
+  const matches = lines
+    .slice(scope.start, scope.end)
+    .flatMap((line, index) => (line === declaration ? [scope.start + index] : []));
+  if (matches.length !== 1) {
+    throw new Error(`pnpm lockfile must declare exactly one ${key} mapping`);
+  }
+  const start = matches[0]!;
+  let end = scope.end;
+  for (let index = start + 1; index < scope.end; index += 1) {
+    const line = lines[index] ?? "";
+    if (line && line.length - line.trimStart().length <= indent) {
+      end = index;
+      break;
+    }
+  }
+  return { start, end };
+}
+
+function verifyYamlLockfile(lockfileText: string) {
+  const lines = lockfileText.split("\n");
+  const body = (range: LineRange) => lines.slice(range.start + 1, range.end);
+  if (lines.filter((line) => line === "lockfileVersion: '9.0'").length !== 1) {
+    throw new Error("pnpm lockfile must use lockfileVersion 9.0");
+  }
+  const importers = findLockfileMapping(lines, "importers", 0);
+  const rootImporter = findLockfileMapping(lines, ".", 2, importers);
+  const dependencies = findLockfileMapping(lines, "dependencies", 4, rootImporter);
+  const yamlImporter = findLockfileMapping(lines, "yaml", 6, dependencies);
+  const importerEntries = body(yamlImporter).filter(Boolean);
+  if (
+    importerEntries.length !== 2 ||
+    importerEntries[0] !== `        specifier: ${YAML_PACKAGE_VERSION}` ||
+    importerEntries[1] !== `        version: ${YAML_PACKAGE_VERSION}`
+  ) {
+    throw new Error(`pnpm root importer must pin yaml exactly to ${YAML_PACKAGE_VERSION}`);
+  }
+
+  const packages = findLockfileMapping(lines, "packages", 0);
+  const yamlPackage = findLockfileMapping(lines, `yaml@${YAML_PACKAGE_VERSION}`, 2, packages);
+  const resolution = `    resolution: {integrity: ${YAML_PACKAGE_INTEGRITY}}`;
+  if (
+    body(yamlPackage)
+      .filter((line) => line.trimStart().startsWith("resolution:"))
+      .join("\n") !== resolution
+  ) {
+    throw new Error(`pnpm lockfile must bind yaml@${YAML_PACKAGE_VERSION} to its exact integrity`);
+  }
+
+  const snapshots = findLockfileMapping(lines, "snapshots", 0);
+  if (
+    body(snapshots).filter((line) => line === `  yaml@${YAML_PACKAGE_VERSION}: {}`).length !== 1
+  ) {
+    throw new Error(
+      `pnpm lockfile yaml@${YAML_PACKAGE_VERSION} snapshot must have no dependencies`,
+    );
+  }
+}
+
+function parseVerifiedYamlDocuments(
+  repoRoot: string,
+  toolingSha: string,
+  sources: [string, string, string],
+  runtime: ReleasePlanRuntime,
+): [unknown, unknown, unknown] {
+  const packageJsonBytes = readGitBytes(repoRoot, toolingSha, "package.json");
+  const lockfileBytes = readGitBytes(repoRoot, toolingSha, "pnpm-lock.yaml");
+  let packageJson: { dependencies?: Record<string, unknown> };
+  try {
+    packageJson = JSON.parse(packageJsonBytes.toString("utf8")) as typeof packageJson;
+  } catch (error) {
+    throw new Error("tooling package.json is invalid JSON", { cause: error });
+  }
+  if (packageJson.dependencies?.yaml !== YAML_PACKAGE_VERSION) {
+    throw new Error(`tooling package.json must pin yaml exactly to ${YAML_PACKAGE_VERSION}`);
+  }
+  verifyYamlLockfile(lockfileBytes.toString("utf8"));
+  return runtime.parseYamlDocuments(sources);
+}
+
+function withCandidateSnapshot<T>(
+  repoRoot: string,
+  candidateSha: string,
+  callback: (snapshotRoot: string) => T,
+): T {
+  const snapshotRoot = mkdtempSync(join(tmpdir(), "openclaw-release-candidate-"));
+  try {
+    const tree = execFileSync(
+      "git",
+      ["ls-tree", "-r", "-z", candidateSha, "--", "package.json", "extensions", "packages"],
+      { cwd: repoRoot },
+    ).toString("utf8");
+    const inventoryPaths: string[] = [];
+    for (const entry of tree.split("\0").filter(Boolean)) {
+      const [metadata, path] = entry.split("\t");
+      if (
+        !path ||
+        (path !== "package.json" &&
+          !/^extensions\/[^/]+\/(?:package\.json|README\.md)$/u.test(path) &&
+          !/^packages\/[^/]+\/package\.json$/u.test(path))
+      ) {
+        continue;
+      }
+      if (metadata?.startsWith("120000 ")) {
+        throw new Error("candidate package inventory must not contain symbolic links");
+      }
+      inventoryPaths.push(path);
+    }
+    if (!inventoryPaths.includes("package.json")) {
+      throw new Error("candidate package.json is missing");
+    }
+    const archivePath = join(snapshotRoot, "candidate.tar");
+    execFileSync(
+      "git",
+      ["archive", "--format=tar", `--output=${archivePath}`, candidateSha, "--", ...inventoryPaths],
+      { cwd: repoRoot },
+    );
+    execFileSync("tar", ["-xf", archivePath, "-C", snapshotRoot]);
+    mkdirSync(join(snapshotRoot, "extensions"), { recursive: true });
+    return callback(snapshotRoot);
+  } finally {
+    rmSync(snapshotRoot, { force: true, recursive: true });
+  }
+}
+
+export function deriveReleasePlanPolicy(
+  intent: ReleasePlanIntent,
+  version: string,
+  validationIntent?: MainQualificationValidationIntent,
+) {
+  const parsed = parseReleaseVersion(version);
+  if (parsed === null || parsed.version !== version) {
+    throw new Error(`unsupported release version: ${version}`);
+  }
+  if (intent !== "main-qualification" && validationIntent !== undefined) {
+    throw new Error("validation intent is only valid for main-qualification");
+  }
+  const purpose: ReleasePlanPurpose | undefined =
+    intent === "main-qualification" ||
+    intent === "diagnostic" ||
+    intent === "postpublish-confidence"
+      ? intent
+      : intent === "publish"
+        ? parsed.channel === "stable"
+          ? "stable-publish"
+          : "beta-publish"
+        : undefined;
+  if (!purpose) {
+    throw new Error("unsupported release plan intent");
+  }
+  const tag = intent === "main-qualification" || intent === "diagnostic" ? null : `v${version}`;
+  return {
+    ...resolveReleaseValidationIntent(releaseValidationIntentForPurpose(purpose, validationIntent)),
+    purpose,
+    tag,
+  };
+}
+
+function collectAllowedGroups(workflowDocument: unknown): string[] {
+  const workflow = workflowDocument as {
+    on?: { workflow_dispatch?: { inputs?: { rerun_group?: { options?: unknown } } } };
+  };
+  const options = workflow.on?.workflow_dispatch?.inputs?.rerun_group?.options;
+  if (
+    !Array.isArray(options) ||
+    options.length === 0 ||
+    options.some((entry) => typeof entry !== "string" || !entry)
+  ) {
+    throw new Error(`${VALIDATION_WORKFLOW_PATH} must declare rerun_group choice options`);
+  }
+  const groups = [...new Set(options)];
+  if (groups.length !== options.length) {
+    throw new Error(`${VALIDATION_WORKFLOW_PATH} rerun_group options must be unique`);
+  }
+  return groups.toSorted(compareAscii);
+}
+
+function readPackageManifest(path: string): PluginPackageJson {
+  return JSON.parse(readFileSync(path, "utf8")) as PluginPackageJson;
+}
+
+function collectCorePackagePolicy(
+  workflowText: string,
+  workflowDocument: unknown,
+): CorePackagePolicy[] {
+  const workflow = workflowDocument as {
+    jobs?: Record<string, { steps?: Array<{ env?: { CORE_PACKAGE_DIRS?: unknown } }> }>;
+  };
+  const declarations = Object.values(workflow.jobs ?? {}).flatMap((job) =>
+    (job.steps ?? [])
+      .map((step) => step.env?.CORE_PACKAGE_DIRS)
+      .filter((value): value is string => typeof value === "string"),
+  );
+  const [declaration] = declarations;
+  if (declarations.length !== 1 || !declaration) {
+    throw new Error(`${NPM_PUBLICATION_WORKFLOW_PATH} must declare one CORE_PACKAGE_DIRS owner`);
+  }
+  const paths = declaration.trim().split(/\s+/u).filter(Boolean);
+  if (
+    paths.length === 0 ||
+    new Set(paths).size !== paths.length ||
+    paths.some((path) => !/^packages\/[a-z0-9-]+$/u.test(path))
+  ) {
+    throw new Error(`${NPM_PUBLICATION_WORKFLOW_PATH} has invalid CORE_PACKAGE_DIRS`);
+  }
+  const dependencyGates = new Map<string, string>();
+  for (const match of workflowText.matchAll(
+    /\[\[ "\$package_dir" == "(packages\/[a-z0-9-]+)" \]\][^\n]*dependencies\?\.\["([^"]+)"\]/gu,
+  )) {
+    if (match[1] && match[2]) {
+      dependencyGates.set(match[1], match[2]);
+    }
+  }
+  for (const path of dependencyGates.keys()) {
+    if (!paths.includes(path)) {
+      throw new Error(`${NPM_PUBLICATION_WORKFLOW_PATH} gates an undeclared core package: ${path}`);
+    }
+  }
+  return paths
+    .map((path) => {
+      const dependency = dependencyGates.get(path);
+      return dependency ? { path, dependency } : { path };
+    })
+    .toSorted((left, right) => compareAscii(left.path, right.path));
+}
+
+function collectPackageInventory(
+  snapshotRoot: string,
+  rootManifest: PluginPackageJson,
+  corePackages: CorePackagePolicy[],
+) {
+  const version = rootManifest.version;
+  if (typeof version !== "string" || !version) {
+    throw new Error("candidate package.json version is required");
+  }
+  const packages = new Map<
+    string,
+    { name: string; source: string; version: string; targets: Set<string> }
+  >();
+  const addPackage = (manifest: PluginPackageJson, targets: string[], source: string) => {
+    if (typeof manifest.name !== "string" || typeof manifest.version !== "string") {
+      throw new Error(`${source} must declare package name and version`);
+    }
+    const existing = packages.get(manifest.name);
+    if (existing && existing.source !== source) {
+      throw new Error(
+        `package inventory source mismatch for ${manifest.name}: ${existing.source} and ${source}`,
+      );
+    }
+    if (existing && existing.version !== manifest.version) {
+      throw new Error(`package inventory version mismatch for ${manifest.name}`);
+    }
+    const entry = existing ?? {
+      name: manifest.name,
+      source,
+      version: manifest.version,
+      targets: new Set<string>(),
+    };
+    for (const target of targets) {
+      entry.targets.add(target);
+    }
+    packages.set(manifest.name, entry);
+  };
+  addPackage({ name: "openclaw", version }, ["npm"], "package.json");
+  const pluginCandidates = collectExtensionPackageJsonCandidates(snapshotRoot);
+  for (const [target, plugins] of [
+    ["clawhub", collectPublishablePluginPackagesFromCandidates(pluginCandidates, "clawhub")],
+    ["npm", collectPublishablePluginPackagesFromCandidates(pluginCandidates, "npm")],
+  ] as const) {
+    for (const plugin of plugins) {
+      addPackage(
+        { name: plugin.packageName, version: plugin.version },
+        [target],
+        `${plugin.packageDir}/package.json`,
+      );
+    }
+  }
+  for (const policy of corePackages) {
+    const manifestPath = join(snapshotRoot, policy.path, "package.json");
+    if (!existsSync(manifestPath)) {
+      if (policy.dependency && typeof rootManifest.dependencies?.[policy.dependency] === "string") {
+        throw new Error(
+          `publishable core package manifest is missing: ${policy.path}/package.json`,
+        );
+      }
+      continue;
+    }
+    const manifest = readPackageManifest(manifestPath);
+    if (policy.dependency && typeof rootManifest.dependencies?.[policy.dependency] !== "string") {
+      continue;
+    }
+    if (!policy.dependency && manifest.openclaw?.release?.publishToNpm !== true) {
+      continue;
+    }
+    if (manifest.version !== version) {
+      throw new Error(`${policy.path} version must match openclaw ${version}`);
+    }
+    addPackage(manifest, ["npm"], `${policy.path}/package.json`);
+  }
+  return [...packages.values()]
+    .map((entry) => ({
+      name: entry.name,
+      version: entry.version,
+      targets: [...entry.targets].toSorted(compareAscii),
+    }))
+    .toSorted((left, right) => compareAscii(left.name, right.name));
+}
+
+function collectPlatformSources(workflowText: string, workflowDocument: unknown) {
+  const platforms = new Map<string, string>();
+  const addPlatform = (id: string, source: string) => {
+    const existing = platforms.get(id);
+    if (existing && existing !== source) {
+      throw new Error(
+        `${PUBLICATION_WORKFLOW_PATH} declares conflicting platform ${id}: ${existing} and ${source}`,
+      );
+    }
+    platforms.set(id, source);
+  };
+  const promotionPattern = /promote_([a-z0-9_]+)_release_assets?\(\)\s*\{([\s\S]*?)^\s*\}/gmu;
+  const dispatchPattern =
+    /dispatch_workflow(?:_at_ref)?\s+(?:(?:"[^"]+"|'[^']+')\s+){0,2}([a-z0-9][a-z0-9-]+\.yml)/u;
+  for (const match of workflowText.matchAll(promotionPattern)) {
+    const id = match[1]?.replaceAll("_", "-");
+    const workflowName = dispatchPattern.exec(match[2] ?? "")?.[1];
+    if (!id || !workflowName) {
+      throw new Error(`${PUBLICATION_WORKFLOW_PATH} has an invalid platform promotion function`);
+    }
+    addPlatform(id, `.github/workflows/${workflowName}`);
+  }
+  const workflow = workflowDocument as {
+    jobs?: Record<string, { uses?: unknown }>;
+  };
+  for (const [jobId, job] of Object.entries(workflow.jobs ?? {})) {
+    if (!jobId.startsWith("publish_") || typeof job.uses !== "string") {
+      continue;
+    }
+    const match = /^\.\/\.github\/workflows\/([a-z0-9][a-z0-9-]+\.yml)$/u.exec(job.uses);
+    if (!match?.[1]) {
+      throw new Error(`${PUBLICATION_WORKFLOW_PATH} has an invalid reusable publication workflow`);
+    }
+    addPlatform(
+      jobId.slice("publish_".length).replaceAll("_", "-"),
+      `.github/workflows/${match[1]}`,
+    );
+  }
+  if (platforms.size === 0) {
+    throw new Error(`${PUBLICATION_WORKFLOW_PATH} does not declare platform publication workflows`);
+  }
+  return [...platforms.entries()].toSorted(([left], [right]) => compareAscii(left, right));
+}
+
+function collectPlatformInventory(
+  repoRoot: string,
+  toolingSha: string,
+  workflowText: string,
+  workflowDocument: unknown,
+) {
+  return collectPlatformSources(workflowText, workflowDocument).map(([id, source]) => {
+    if (!gitPathExists(repoRoot, toolingSha, source)) {
+      throw new Error(`release platform workflow does not exist at tooling SHA: ${source}`);
+    }
+    return { id, source };
+  });
+}
+
+function readCandidateInventory(
+  repoRoot: string,
+  candidateSha: string,
+  corePackages: CorePackagePolicy[],
+) {
+  return withCandidateSnapshot(repoRoot, candidateSha, (snapshotRoot) => {
+    const rootPackage = readPackageManifest(join(snapshotRoot, "package.json"));
+    if (typeof rootPackage.version !== "string" || !rootPackage.version) {
+      throw new Error("candidate package.json version is required");
+    }
+    return {
+      version: rootPackage.version,
+      packages: collectPackageInventory(snapshotRoot, rootPackage, corePackages),
+    };
+  });
+}
+
+function resolveSource(params: ReleasePlanSource) {
+  const repoRoot = resolve(params.repoRoot ?? ".");
+  const candidateSha = requireExactSha(params.candidateSha, "candidate SHA");
+  const toolingSha = requireExactSha(params.toolingSha, "tooling SHA");
+  const toolingFullRef = requireQualifiedRef(params.toolingFullRef, "tooling full ref");
+  if (resolveCommit(repoRoot, candidateSha, "candidate SHA") !== candidateSha) {
+    throw new Error("candidate SHA does not resolve to itself");
+  }
+  const toolingRef = toolingFullRef.replace(/^refs\/(?:heads|tags)\//u, "");
+  const verifiedTooling = verifyReleaseToolingIdentity({
+    repository: REPOSITORY,
+    workflowFullRef: toolingFullRef,
+    workflowRef: toolingRef,
+    workflowSha: toolingSha,
+    ...(params.runGh ? { runGh: params.runGh } : {}),
+  });
+  if (
+    params.intent !== "diagnostic" &&
+    params.intent !== "main-qualification" &&
+    verifiedTooling.route !== "protected-tag"
+  ) {
+    throw new Error(`${params.intent} tooling must use a release-publish tag bound to its SHA`);
+  }
+  return { candidateSha, repoRoot, toolingFullRef, toolingSha };
+}
+
+function produceReleasePlan(params: ReleasePlanSource, runtime: ReleasePlanRuntime): ReleasePlan {
+  const { candidateSha, repoRoot, toolingFullRef, toolingSha } = resolveSource(params);
+  const validationWorkflow = readGitText(repoRoot, toolingSha, VALIDATION_WORKFLOW_PATH);
+  const publicationWorkflow = readGitText(repoRoot, toolingSha, PUBLICATION_WORKFLOW_PATH);
+  const npmPublicationWorkflow = readGitText(repoRoot, toolingSha, NPM_PUBLICATION_WORKFLOW_PATH);
+  const [validationDocument, publicationDocument, npmPublicationDocument] =
+    parseVerifiedYamlDocuments(
+      repoRoot,
+      toolingSha,
+      [validationWorkflow, publicationWorkflow, npmPublicationWorkflow],
+      runtime,
+    );
+  const candidate = readCandidateInventory(
+    repoRoot,
+    candidateSha,
+    collectCorePackagePolicy(npmPublicationWorkflow, npmPublicationDocument),
+  );
+  const policy = deriveReleasePlanPolicy(params.intent, candidate.version, params.validationIntent);
+  // ReleasePlan binds the candidate bytes. A branch used only to make the FRV
+  // workflow reachable is dispatch state and must not become plan authority.
+  const expectedCandidateRef =
+    params.intent === "diagnostic" || params.intent === "main-qualification"
+      ? candidateSha
+      : `refs/tags/v${candidate.version}`;
+  if (params.candidateRef !== expectedCandidateRef) {
+    throw new Error(`${params.intent} candidate ref must be ${expectedCandidateRef}`);
+  }
+  if (
+    params.intent === "postpublish-confidence" &&
+    resolveCommit(repoRoot, params.candidateRef, "published candidate tag") !== candidateSha
+  ) {
+    throw new Error("published candidate tag does not resolve to the candidate SHA");
+  }
+  return validateReleasePlan({
+    schema: RELEASE_PLAN_SCHEMA,
+    release_id: candidate.version,
+    version: candidate.version,
+    tag: policy.tag,
+    candidate_sha: candidateSha,
+    target_context_ref: expectedCandidateRef,
+    purpose: policy.purpose,
+    tooling: {
+      repository: REPOSITORY,
+      workflow_path: VALIDATION_WORKFLOW_PATH,
+      ref: toolingFullRef,
+      sha: toolingSha,
+    },
+    validation: {
+      intent: policy.intent,
+      profile: policy.profile,
+      soak: policy.soak,
+      allowed_groups: collectAllowedGroups(validationDocument),
+    },
+    inventory: {
+      packages: candidate.packages,
+      platforms: collectPlatformInventory(
+        repoRoot,
+        toolingSha,
+        publicationWorkflow,
+        publicationDocument,
+      ),
+    },
+  });
+}
+
+function verifyReleasePlanLock(
+  lockJson: string,
+  params: ReleasePlanSource,
+  runtime: ReleasePlanRuntime,
+): ReleasePlanLock {
+  const expectedPlan = produceReleasePlan(params, runtime);
+  const lock = parseReleasePlanLockJson(lockJson);
+  if (canonicalReleasePlanJson(lock.plan) !== canonicalReleasePlanJson(expectedPlan)) {
+    throw new Error("release plan does not match repository-derived authority");
+  }
+  return lock;
+}
+
+export function runReleasePlanProducerOperation(
+  request: ReleasePlanProducerRequest,
+  runtime: ReleasePlanRuntime,
+): ReleasePlan | ReleasePlanLock | string {
+  const params = { ...request.params, runGh: runtime.runGh };
+  if (request.operation === "produce") {
+    return produceReleasePlan(params, runtime);
+  }
+  if (request.operation === "verify-lock") {
+    return verifyReleasePlanLock(request.lockJson, params, runtime);
+  }
+  return canonicalReleasePlanLockJson(createReleasePlanLock(produceReleasePlan(params, runtime)));
+}
diff --git a/scripts/release-plan-producer.mts b/scripts/release-plan-producer.mts
new file mode 100644
index 000000000000..3e6aa7c0eaa4
--- /dev/null
+++ b/scripts/release-plan-producer.mts
@@ -0,0 +1,544 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import { isBuiltin } from "node:module";
+import { join, posix, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { deserialize, serialize } from "node:v8";
+
+export type ReleasePlanIntent =
+  | "publish"
+  | "diagnostic"
+  | "postpublish-confidence"
+  | "main-qualification";
+export type MainQualificationValidationIntent = "main-daily" | "main-weekly";
+type RunGh = (args: string[]) => string;
+type ReleasePlanSourceBase = {
+  repoRoot?: string;
+  candidateSha: string;
+  candidateRef: string;
+  toolingSha: string;
+  toolingFullRef: string;
+  runGh?: RunGh;
+};
+export type ReleasePlanSource =
+  | (ReleasePlanSourceBase & {
+      intent: "main-qualification";
+      validationIntent: MainQualificationValidationIntent;
+    })
+  | (ReleasePlanSourceBase & {
+      intent: Exclude<ReleasePlanIntent, "main-qualification">;
+      validationIntent?: never;
+    });
+type ReleasePlan = {
+  schema: string;
+  release_id: string;
+  version: string;
+  tag: string | null;
+  candidate_sha: string;
+  target_context_ref: string;
+  purpose: string;
+  tooling: { repository: string; workflow_path: string; ref: string; sha: string };
+  validation: {
+    intent: string;
+    profile: string;
+    soak: boolean;
+    allowed_groups: string[];
+  };
+  inventory: {
+    packages: Array<{ name: string; version: string; targets: string[] }>;
+    platforms: Array<{ id: string; source: string }>;
+  };
+};
+type ReleasePlanLock = Record<"schema" | "digest", string> & { plan: ReleasePlan };
+
+const REPOSITORY = "openclaw/openclaw";
+const EXECUTION_ROOT = fileURLToPath(new URL("..", import.meta.url));
+const BOOTSTRAP_PATH = "scripts/release-plan-producer.mts",
+  CORE_PATH = "scripts/release-plan-producer-core.mts";
+const TOOLING_MODULE_PATHS = [
+  "packages/normalization-core/src/record-coerce.ts",
+  "packages/normalization-core/src/string-coerce.ts",
+  "packages/plugin-package-contract/src/index.ts",
+  "scripts/lib/npm-publish-plan.mjs",
+  "scripts/lib/plugin-publication-candidates.ts",
+  "scripts/lib/plugin-publication-collector.ts",
+  "scripts/lib/record-shared.mjs",
+  "scripts/lib/release-version.mjs",
+  CORE_PATH,
+  "scripts/release-plan-contract.mjs",
+  "scripts/release-tooling-identity.mjs",
+  "scripts/release-validation-intent.mjs",
+] as const;
+const PROTECTED_TAG_PATTERN = /^release-publish\/([a-f0-9]{12})-([1-9][0-9]*)$/u;
+const MAX_TOOLING_FILE_BYTES = 512 * 1024,
+  MAX_TOOLING_BYTES = 2 * 1024 * 1024;
+const YAML_PACKAGE_TREE_SHA256 = "610ccacfe592d226ac1eb04842d1f591c5381f2a68b9f785643101d10db52c27";
+const YAML_PACKAGE_MAX_FILES = 512;
+const YAML_PACKAGE_MAX_ENTRIES = 1024;
+const YAML_PACKAGE_MAX_BYTES = 4 * 1024 * 1024;
+const compareAscii = (left: string, right: string) => (left < right ? -1 : left > right ? 1 : 0);
+
+type ToolingModule = { path: string; bytes: Buffer; imports: Array<[string, string]> };
+type YamlEntry =
+  | { kind: "directory"; path: string }
+  | { kind: "file"; path: string; bytes: Buffer };
+type SerializableSource = Omit<ReleasePlanSourceBase, "runGh"> & Record<string, unknown>;
+type ProducerRequest =
+  | { operation: "produce" | "produce-lock"; params: SerializableSource }
+  | { operation: "verify-lock"; lockJson: string; params: SerializableSource };
+
+const CHILD_RUNNER = String.raw`
+import { createHash } from "node:crypto"; import { readFileSync } from "node:fs";
+import { createRequire, isBuiltin, registerHooks } from "node:module";
+import { deserialize, serialize } from "node:v8";
+const TOOLING_ROOT = "file:///__openclaw_verified_tooling__/", YAML_ROOT = "file:///__openclaw_verified_yaml__/";
+const YAML_ABSOLUTE_ROOT = "/__openclaw_verified_yaml__", CORE_PATH = ${JSON.stringify(CORE_PATH)};
+const EXPECTED_TOOLING_PATHS = ${JSON.stringify(TOOLING_MODULE_PATHS)};
+const compareAscii = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const fail = message => { throw new Error(message); };
+const toolingUrl = path => new URL(path, TOOLING_ROOT).href, yamlUrl = path => new URL(path, YAML_ROOT).href;
+const safePath = path => typeof path === "string" && path.length > 0 &&
+  /^[\x20-\x7e]+$/.test(path) && !path.includes("\\") && !path.startsWith("/") &&
+  !path.split("/").some(part => part === "." || part === "..");
+try {
+  const payload = deserialize(readFileSync(0)), expectedPaths = [...EXPECTED_TOOLING_PATHS].sort(compareAscii);
+  if (!Array.isArray(payload.toolingModules) || payload.toolingModules.length !== expectedPaths.length) fail("verified tooling module set is incomplete");
+  const toolingModules = new Map();
+  for (const record of payload.toolingModules) {
+    if (!record || !expectedPaths.includes(record.path) || toolingModules.has(record.path) || !Array.isArray(record.imports)) fail("verified tooling module record is invalid");
+    toolingModules.set(record.path, { bytes: Buffer.from(record.bytes),
+      format: record.path.endsWith(".mjs") ? "module" : "module-typescript",
+      imports: new Map(record.imports) });
+  }
+  if ([...toolingModules.keys()].sort(compareAscii).some((path, index) => path !== expectedPaths[index])) fail("verified tooling module paths do not match the allowlist");
+  if (!Array.isArray(payload.yamlEntries) || payload.yamlEntries.length > ${YAML_PACKAGE_MAX_ENTRIES}) fail("verified yaml retained tree has too many entries");
+  const yamlModules = new Map(), yamlRecords = []; let yamlFiles = 0, yamlBytes = 0;
+  for (const entry of payload.yamlEntries) {
+    if (!entry || !safePath(entry.path)) fail("verified yaml retained tree contains an unsafe path");
+    if (entry.kind === "directory") {
+      yamlRecords.push(JSON.stringify(["directory", entry.path])); continue;
+    }
+    if (entry.kind !== "file" || yamlModules.has(entry.path)) fail("verified yaml retained tree contains an invalid entry");
+    const bytes = Buffer.from(entry.bytes); yamlFiles += 1; yamlBytes += bytes.byteLength;
+    if (yamlFiles > ${YAML_PACKAGE_MAX_FILES} || yamlBytes > ${YAML_PACKAGE_MAX_BYTES}) fail("verified yaml retained tree exceeds its bounds");
+    yamlModules.set(entry.path, bytes);
+    yamlRecords.push(JSON.stringify(["file", entry.path, bytes.byteLength, createHash("sha256").update(bytes).digest("hex")]));
+  }
+  const yamlManifest = yamlRecords.sort(compareAscii).join("\n") + "\n";
+  if (createHash("sha256").update(yamlManifest, "ascii").digest("hex") !== ${JSON.stringify(YAML_PACKAGE_TREE_SHA256)}) fail("verified yaml retained tree digest mismatch");
+  const packageBytes = yamlModules.get("package.json");
+  if (!packageBytes) fail("verified yaml retained package.json is missing");
+  const yamlPackage = JSON.parse(packageBytes.toString("utf8"));
+  if (yamlPackage.name !== "yaml" || yamlPackage.version !== "2.9.0") fail("verified yaml retained package identity mismatch");
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      if (isBuiltin(specifier)) return nextResolve(specifier, context);
+      if (context.parentURL?.startsWith(TOOLING_ROOT)) {
+        const parentPath = context.parentURL.slice(TOOLING_ROOT.length);
+        const targetPath = toolingModules.get(parentPath)?.imports.get(specifier);
+        if (!targetPath) fail("verified tooling import is not allowlisted");
+        return { url: toolingUrl(targetPath), format: toolingModules.get(targetPath).format, shortCircuit: true };
+      }
+      if (specifier === toolingUrl(CORE_PATH)) return { url: specifier, format: toolingModules.get(CORE_PATH).format, shortCircuit: true };
+      const targetUrl = specifier.startsWith(YAML_ABSOLUTE_ROOT + "/") ?
+        yamlUrl(specifier.slice(YAML_ABSOLUTE_ROOT.length + 1)) :
+        context.parentURL?.startsWith(YAML_ROOT) && specifier.startsWith(".") ?
+          new URL(specifier, context.parentURL).href : undefined;
+      if (targetUrl) {
+        const targetPath = targetUrl.slice(YAML_ROOT.length);
+        if (!yamlModules.has(targetPath)) fail("verified yaml import is not retained");
+        return { url: targetUrl, format: "commonjs", shortCircuit: true };
+      }
+      fail("verified child rejected an external module import");
+    },
+    load(url, context, nextLoad) {
+      if (url.startsWith(TOOLING_ROOT)) {
+        const record = toolingModules.get(url.slice(TOOLING_ROOT.length));
+        if (!record) fail("verified tooling module is not retained");
+        return { format: record.format, source: record.bytes, shortCircuit: true };
+      }
+      if (url.startsWith(YAML_ROOT)) {
+        const bytes = yamlModules.get(url.slice(YAML_ROOT.length));
+        if (!bytes) fail("verified yaml module is not retained");
+        return { format: "commonjs", source: bytes, shortCircuit: true };
+      }
+      if (url.startsWith("node:")) return nextLoad(url, context);
+      fail("verified child rejected an external module load");
+    },
+  });
+  const identityResponses = new Map(payload.identityResponses);
+  if (identityResponses.size !== 1) fail("verified identity response cache must contain exactly one request");
+  const runGh = args => {
+    const key = JSON.stringify(args);
+    if (!identityResponses.has(key)) fail("verified child rejected an uncached GitHub request");
+    return identityResponses.get(key);
+  };
+  let parseYaml;
+  const parseYamlDocuments = sources => {
+    if (!Array.isArray(sources) || sources.length !== 3 || sources.some(value => typeof value !== "string")) fail("verified yaml parser input must contain three workflow strings");
+    if (!parseYaml) {
+      const yaml = createRequire(import.meta.url)(YAML_ABSOLUTE_ROOT + "/dist/index.js");
+      if (typeof yaml.parse !== "function") fail("verified yaml parser must export parse"); parseYaml = yaml.parse;
+    }
+    return sources.map(parseYaml);
+  };
+  const core = await import(toolingUrl(CORE_PATH)), value = core.runReleasePlanProducerOperation(payload.request, { runGh, parseYamlDocuments });
+  process.stdout.write(serialize({ ok: true, value }));
+} catch (error) {
+  process.stdout.write(serialize({ ok: false, message: error instanceof Error ? error.message : String(error) }));
+}
+`;
+
+const gitBytes = (repoRoot: string, args: string[]) =>
+  execFileSync("git", args, {
+    cwd: repoRoot,
+    encoding: null,
+    maxBuffer: 16 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+function requireSha(value: string, label: string) {
+  if (!/^[a-f0-9]{40}$/u.test(value)) {
+    throw new Error(`${label} must be an exact lowercase 40-character commit SHA`);
+  }
+  return value;
+}
+
+function defaultRunGh(args: string[]) {
+  return execFileSync("gh", args, {
+    encoding: "utf8",
+    killSignal: "SIGKILL",
+    maxBuffer: 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 60_000,
+  });
+}
+
+function verifyRemoteTooling(params: ReleasePlanSource, runGh: RunGh) {
+  const sha = requireSha(params.toolingSha, "tooling SHA");
+  const tagRef = params.toolingFullRef.replace(/^refs\/tags\//u, "");
+  const protectedMatch = PROTECTED_TAG_PATTERN.exec(tagRef);
+  let args: string[], failure: string;
+  if (protectedMatch) {
+    if (protectedMatch[1] !== sha.slice(0, 12)) {
+      throw new Error("protected release tooling tag SHA prefix does not match the workflow SHA");
+    }
+    args = ["api", `repos/${REPOSITORY}/git/ref/tags/${tagRef}`, "--method", "GET"];
+    failure = "protected release tooling tag is missing or unreadable";
+  } else if (params.toolingFullRef === "refs/heads/main") {
+    args = ["api", `repos/${REPOSITORY}/compare/${sha}...main`, "--method", "GET"];
+    failure = "main release tooling ancestry could not be verified";
+  } else {
+    throw new Error("release tooling identity must be trusted main or an exact protected tag");
+  }
+  let raw: string;
+  try {
+    raw = runGh(args);
+  } catch (error) {
+    throw new Error(failure, { cause: error });
+  }
+  const response = JSON.parse(raw) as {
+    ref?: unknown;
+    status?: unknown;
+    object?: { type?: unknown; sha?: unknown };
+  };
+  if (
+    protectedMatch &&
+    (response.ref !== params.toolingFullRef ||
+      response.object?.type !== "commit" ||
+      response.object.sha !== sha)
+  ) {
+    throw new Error(
+      "protected release tooling tag is missing, moved, annotated, or bound to the wrong SHA",
+    );
+  }
+  if (!protectedMatch && response.status !== "ahead" && response.status !== "identical") {
+    throw new Error("main release tooling SHA is not reachable from current main");
+  }
+  if (params.intent !== "diagnostic" && params.intent !== "main-qualification" && !protectedMatch) {
+    throw new Error(`${params.intent} tooling must use a release-publish tag bound to its SHA`);
+  }
+  return [[JSON.stringify(args), raw]] as Array<[string, string]>;
+}
+
+function readGitFile(repoRoot: string, sha: string, path: string) {
+  const entry = gitBytes(repoRoot, ["ls-tree", sha, "--", path]).toString("utf8").trim();
+  if (!/^100(?:644|755) blob [a-f0-9]{40}\t/u.test(entry)) {
+    throw new Error(`tooling closure path must be a regular Git blob: ${path}`);
+  }
+  return gitBytes(repoRoot, ["show", `${sha}:${path}`]);
+}
+
+function gitPathExists(repoRoot: string, sha: string, path: string) {
+  try {
+    execFileSync("git", ["cat-file", "-e", `${sha}:${path}`], { cwd: repoRoot, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function collectLiteralImports(source: string) {
+  return [
+    ...new Set(
+      [...source.matchAll(/\b(?:from\s+|import\s*(?:\(\s*)?)["']([^"']+)["']/gu)].map(
+        (match) => match[1]!,
+      ),
+    ),
+  ].toSorted(compareAscii);
+}
+
+function resolveImport(repoRoot: string, sha: string, sourcePath: string, specifier: string) {
+  if (!specifier.startsWith(".") || specifier.startsWith("file:")) {
+    throw new Error(`tooling closure contains an unowned import: ${sourcePath} -> ${specifier}`);
+  }
+  const importedPath = posix.normalize(posix.join(posix.dirname(sourcePath), specifier));
+  if (importedPath === ".." || importedPath.startsWith("../")) {
+    throw new Error(`tooling import escapes repository root: ${sourcePath} -> ${specifier}`);
+  }
+  const candidates = new Set([importedPath]);
+  if (importedPath.endsWith(".js")) {
+    candidates.add(`${importedPath.slice(0, -3)}.ts`);
+  } else if (importedPath.endsWith(".mjs")) {
+    candidates.add(`${importedPath.slice(0, -4)}.mts`);
+  } else if (!posix.extname(importedPath)) {
+    for (const suffix of [".ts", ".mts", ".mjs", "/index.ts"]) {
+      candidates.add(`${importedPath}${suffix}`);
+    }
+  }
+  const existing = [...candidates].filter((path) => gitPathExists(repoRoot, sha, path));
+  if (existing.length !== 1) {
+    throw new Error(
+      `tooling import must resolve to one unambiguous file: ${sourcePath} -> ${specifier}`,
+    );
+  }
+  const [target] = existing;
+  if (!target || !TOOLING_MODULE_PATHS.includes(target as (typeof TOOLING_MODULE_PATHS)[number])) {
+    throw new Error(`tooling import is outside the fixed closure: ${sourcePath} -> ${specifier}`);
+  }
+  return target;
+}
+
+function retainToolingClosure(repoRoot: string, sha: string) {
+  const pending = [CORE_PATH];
+  const modules = new Map<string, ToolingModule>();
+  let totalBytes = 0;
+  while (pending.length > 0) {
+    const path = pending.pop();
+    if (!path || modules.has(path)) {
+      continue;
+    }
+    const bytes = readGitFile(repoRoot, sha, path);
+    totalBytes += bytes.byteLength;
+    if (bytes.byteLength > MAX_TOOLING_FILE_BYTES || totalBytes > MAX_TOOLING_BYTES) {
+      throw new Error("tooling closure exceeds its retained-byte bounds");
+    }
+    const imports: Array<[string, string]> = [];
+    for (const specifier of collectLiteralImports(bytes.toString("utf8"))) {
+      if (isBuiltin(specifier)) {
+        continue;
+      }
+      const target = resolveImport(repoRoot, sha, path, specifier);
+      imports.push([specifier, target]);
+      pending.push(target);
+    }
+    modules.set(path, { path, bytes, imports });
+  }
+  const retained = [...modules.values()].toSorted((left, right) =>
+    compareAscii(left.path, right.path),
+  );
+  if (
+    retained.length !== TOOLING_MODULE_PATHS.length ||
+    retained.some(
+      (record, index) => record.path !== [...TOOLING_MODULE_PATHS].toSorted(compareAscii)[index],
+    )
+  ) {
+    throw new Error("tooling closure does not match the fixed allowlist");
+  }
+  return retained;
+}
+
+function assertSafeYamlPath(path: string) {
+  const components = new Set(path.split("/"));
+  if (
+    !path ||
+    !/^[\x20-\x7e]+$/u.test(path) ||
+    path.includes("\\") ||
+    posix.isAbsolute(path) ||
+    components.has(".") ||
+    components.has("..")
+  ) {
+    throw new Error(`installed yaml package contains an unsafe path: ${JSON.stringify(path)}`);
+  }
+}
+
+function retainYamlPackage() {
+  if (typeof fs.constants.O_NOFOLLOW !== "number") {
+    throw new Error("installed yaml package verification requires O_NOFOLLOW support");
+  }
+  const packageRoot = fs.realpathSync(join(EXECUTION_ROOT, "node_modules", "yaml"));
+  if (!fs.lstatSync(packageRoot).isDirectory()) {
+    throw new Error("installed yaml package root must be a directory");
+  }
+  const entries: YamlEntry[] = [];
+  let fileCount = 0;
+  let totalBytes = 0;
+  const walk = (directory: string, relativeDirectory = "") => {
+    for (const name of fs.readdirSync(directory).toSorted(compareAscii)) {
+      const path = relativeDirectory ? `${relativeDirectory}/${name}` : name;
+      assertSafeYamlPath(path);
+      if (entries.length >= YAML_PACKAGE_MAX_ENTRIES) {
+        throw new Error(`installed yaml package exceeds ${YAML_PACKAGE_MAX_ENTRIES} entries`);
+      }
+      const absolutePath = join(directory, name);
+      const lstat = fs.lstatSync(absolutePath);
+      if (lstat.isSymbolicLink()) {
+        throw new Error(`installed yaml package must not contain symbolic links: ${path}`);
+      }
+      if (lstat.isDirectory()) {
+        entries.push({ kind: "directory", path });
+        walk(absolutePath, path);
+        continue;
+      }
+      if (!lstat.isFile()) {
+        throw new Error("installed yaml package must contain only directories and files");
+      }
+      fileCount += 1;
+      if (fileCount > YAML_PACKAGE_MAX_FILES) {
+        throw new Error(`installed yaml package exceeds ${YAML_PACKAGE_MAX_FILES} files`);
+      }
+      const descriptor = fs.openSync(absolutePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+      let bytes: Buffer;
+      try {
+        const stat = fs.fstatSync(descriptor);
+        if (!stat.isFile()) {
+          throw new Error(`installed yaml package file changed type: ${path}`);
+        }
+        totalBytes += stat.size;
+        if (totalBytes > YAML_PACKAGE_MAX_BYTES) {
+          throw new Error(`installed yaml package exceeds ${YAML_PACKAGE_MAX_BYTES} bytes`);
+        }
+        bytes = fs.readFileSync(descriptor);
+        if (bytes.byteLength !== stat.size) {
+          throw new Error(`installed yaml package file changed while being read: ${path}`);
+        }
+      } finally {
+        fs.closeSync(descriptor);
+      }
+      entries.push({ kind: "file", path, bytes });
+    }
+  };
+  walk(packageRoot);
+  return entries;
+}
+
+const serializableParams = ({ runGh: _runGh, ...source }: ReleasePlanSource) =>
+  source as SerializableSource;
+
+function runOperation(request: ProducerRequest, params: ReleasePlanSource) {
+  const repoRoot = resolve(params.repoRoot ?? ".");
+  const runGh = params.runGh ?? defaultRunGh;
+  const identityResponses = verifyRemoteTooling(params, runGh);
+  const toolingSha = requireSha(params.toolingSha, "tooling SHA");
+  const executionHead = gitBytes(EXECUTION_ROOT, ["rev-parse", "HEAD"]).toString("utf8").trim();
+  if (executionHead !== toolingSha) {
+    throw new Error("tooling bootstrap checkout HEAD must equal tooling SHA");
+  }
+  const bootstrapBytes = readGitFile(repoRoot, toolingSha, BOOTSTRAP_PATH);
+  if (!fs.readFileSync(fileURLToPath(import.meta.url)).equals(bootstrapBytes)) {
+    throw new Error(`tooling bootstrap differs from tooling SHA: ${BOOTSTRAP_PATH}`);
+  }
+  let stdout: Buffer;
+  try {
+    stdout = execFileSync(process.execPath, ["--input-type=module", "-e", CHILD_RUNNER], {
+      cwd: repoRoot,
+      encoding: null,
+      env: {},
+      input: serialize({
+        identityResponses,
+        request,
+        toolingModules: retainToolingClosure(repoRoot, toolingSha),
+        yamlEntries: retainYamlPackage(),
+      }),
+      maxBuffer: 16 * 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (error) {
+    throw new Error("verified release plan child failed", { cause: error });
+  }
+  const envelope = deserialize(stdout) as { ok?: unknown; value?: unknown; message?: unknown };
+  if (envelope.ok !== true) {
+    throw new Error(
+      typeof envelope.message === "string" ? envelope.message : "verified child failed",
+    );
+  }
+  return envelope.value;
+}
+
+export function produceReleasePlan(params: ReleasePlanSource): ReleasePlan {
+  return runOperation(
+    { operation: "produce", params: serializableParams(params) },
+    params,
+  ) as ReleasePlan;
+}
+
+export function verifyReleasePlanLock(lockJson: string, params: ReleasePlanSource) {
+  return runOperation(
+    { operation: "verify-lock", lockJson, params: serializableParams(params) },
+    params,
+  ) as ReleasePlanLock;
+}
+
+function requiredOption(args: string[], name: string) {
+  const index = args.indexOf(name);
+  const value = index >= 0 ? args[index + 1] : undefined;
+  if (!value || value.startsWith("-")) {
+    throw new Error(`${name} is required`);
+  }
+  return value;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const intent = requiredOption(args, "--intent") as ReleasePlanIntent;
+  if (!["publish", "diagnostic", "postpublish-confidence", "main-qualification"].includes(intent)) {
+    throw new Error(
+      "--intent must be publish, diagnostic, postpublish-confidence, or main-qualification",
+    );
+  }
+  const source = {
+    candidateSha: requiredOption(args, "--candidate-sha"),
+    candidateRef: requiredOption(args, "--candidate-ref"),
+    toolingSha: requiredOption(args, "--tooling-sha"),
+    toolingFullRef: requiredOption(args, "--tooling-full-ref"),
+  };
+  const params = {
+    ...source,
+    intent,
+    ...(intent === "main-qualification"
+      ? {
+          validationIntent: requiredOption(
+            args,
+            "--validation-intent",
+          ) as MainQualificationValidationIntent,
+        }
+      : {}),
+  } as ReleasePlanSource;
+  process.stdout.write(
+    runOperation(
+      { operation: "produce-lock", params: serializableParams(params) },
+      params,
+    ) as string,
+  );
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    console.error("[release-plan-producer] FAILED (exit 1)");
+    process.exitCode = 1;
+  }
+}
diff --git a/scripts/release-validation-intent.d.mts b/scripts/release-validation-intent.d.mts
new file mode 100644
index 000000000000..be1056030ecd
--- /dev/null
+++ b/scripts/release-validation-intent.d.mts
@@ -0,0 +1,35 @@
+export type ReleaseValidationIntent =
+  | "release-beta"
+  | "release-stable"
+  | "main-daily"
+  | "main-weekly"
+  | "diagnostic-full";
+
+export type ReleaseValidationProfile = "beta" | "stable" | "full";
+
+export type ReleaseValidationPurpose =
+  | "beta-publish"
+  | "stable-publish"
+  | "diagnostic"
+  | "postpublish-confidence"
+  | "main-qualification";
+
+export type ReleaseValidationIntentPolicy = {
+  intent: ReleaseValidationIntent;
+  profile: ReleaseValidationProfile;
+  publishable: boolean;
+  soak: boolean;
+};
+
+export function resolveReleaseValidationIntent(
+  intent: string,
+  assertions?: {
+    profile?: string;
+    soak?: boolean;
+  },
+): ReleaseValidationIntentPolicy;
+
+export function releaseValidationIntentForPurpose(
+  purpose: string,
+  requestedIntent?: string,
+): ReleaseValidationIntent;
diff --git a/scripts/release-validation-intent.mjs b/scripts/release-validation-intent.mjs
new file mode 100644
index 000000000000..fc99b657734e
--- /dev/null
+++ b/scripts/release-validation-intent.mjs
@@ -0,0 +1,56 @@
+const RELEASE_VALIDATION_INTENTS = Object.freeze({
+  "release-beta": Object.freeze({ profile: "beta", publishable: true, soak: false }),
+  "release-stable": Object.freeze({ profile: "stable", publishable: true, soak: true }),
+  "main-daily": Object.freeze({ profile: "beta", publishable: false, soak: false }),
+  "main-weekly": Object.freeze({ profile: "full", publishable: false, soak: true }),
+  "diagnostic-full": Object.freeze({ profile: "full", publishable: false, soak: true }),
+});
+
+const PURPOSE_INTENTS = Object.freeze({
+  "beta-publish": Object.freeze(["release-beta"]),
+  "stable-publish": Object.freeze(["release-stable"]),
+  diagnostic: Object.freeze(["diagnostic-full"]),
+  "postpublish-confidence": Object.freeze(["diagnostic-full"]),
+  "main-qualification": Object.freeze(["main-daily", "main-weekly"]),
+});
+
+function displayValue(value) {
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+
+export function resolveReleaseValidationIntent(intent, assertions = {}) {
+  if (typeof intent !== "string" || !Object.hasOwn(RELEASE_VALIDATION_INTENTS, intent)) {
+    throw new Error(`unsupported release validation intent: ${displayValue(intent)}`);
+  }
+  const policy = RELEASE_VALIDATION_INTENTS[intent];
+  if (assertions.profile !== undefined && assertions.profile !== policy.profile) {
+    throw new Error(
+      `release validation intent ${intent} profile assertion conflicts: expected ${policy.profile}, got ${displayValue(assertions.profile)}`,
+    );
+  }
+  if (assertions.soak !== undefined && assertions.soak !== policy.soak) {
+    throw new Error(
+      `release validation intent ${intent} soak assertion conflicts: expected ${policy.soak}, got ${displayValue(assertions.soak)}`,
+    );
+  }
+  return { intent, ...policy };
+}
+
+export function releaseValidationIntentForPurpose(purpose, requestedIntent) {
+  if (typeof purpose !== "string" || !Object.hasOwn(PURPOSE_INTENTS, purpose)) {
+    throw new Error(`unsupported release plan purpose: ${displayValue(purpose)}`);
+  }
+  const allowedIntents = PURPOSE_INTENTS[purpose];
+  if (requestedIntent === undefined) {
+    if (allowedIntents.length !== 1) {
+      throw new Error(`release plan purpose ${purpose} requires an explicit validation intent`);
+    }
+    return allowedIntents[0];
+  }
+  if (typeof requestedIntent !== "string" || !allowedIntents.includes(requestedIntent)) {
+    throw new Error(
+      `release plan purpose ${purpose} does not allow validation intent: ${displayValue(requestedIntent)}`,
+    );
+  }
+  return requestedIntent;
+}
diff --git a/test/fixtures/release-plan-lock-v1.compatibility.json b/test/fixtures/release-plan-lock-v1.compatibility.json
new file mode 100644
index 000000000000..eba4f758f8b4
--- /dev/null
+++ b/test/fixtures/release-plan-lock-v1.compatibility.json
@@ -0,0 +1 @@
+{"digest":"sha256:0601f18ff710fbb04933b15dae909bc194328d37e1aa146e19a0ab6383f9a676","plan":{"candidate_sha":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","inventory":{"packages":[{"name":"@openclaw/example","targets":["clawhub","npm"],"version":"2026.8.1-beta.2"},{"name":"openclaw","targets":["npm"],"version":"2026.8.1-beta.2"}],"platforms":[{"id":"android","source":".github/workflows/android-release.yml"},{"id":"docker","source":".github/workflows/docker-release.yml"},{"id":"vcr","source":".github/workflows/vercel-container-registry-publish.yml"},{"id":"windows","source":".github/workflows/windows-node-release.yml"}]},"purpose":"beta-publish","release_id":"2026.8.1-beta.2","schema":"openclaw.release-plan.v1","tag":"v2026.8.1-beta.2","target_context_ref":"refs/tags/v2026.8.1-beta.2","tooling":{"ref":"refs/tags/release-publish/bbbbbbbbbbbb-123","repository":"openclaw/openclaw","sha":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","workflow_path":".github/workflows/full-release-validation.yml"},"validation":{"allowed_groups":["all","ci","package"],"intent":"release-beta","profile":"beta","soak":false},"version":"2026.8.1-beta.2"},"schema":"openclaw.release-plan-lock.v1"}
diff --git a/test/fixtures/release-plan-v1.source.json b/test/fixtures/release-plan-v1.source.json
new file mode 100644
index 000000000000..01efac2c0d2f
--- /dev/null
+++ b/test/fixtures/release-plan-v1.source.json
@@ -0,0 +1 @@
+{"candidate_sha":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","inventory":{"packages":[{"name":"@openclaw/example","targets":["clawhub","npm"],"version":"2026.8.1-beta.2"},{"name":"openclaw","targets":["npm"],"version":"2026.8.1-beta.2"}],"platforms":[{"id":"android","source":".github/workflows/android-release.yml"},{"id":"docker","source":".github/workflows/docker-release.yml"},{"id":"vcr","source":".github/workflows/vercel-container-registry-publish.yml"},{"id":"windows","source":".github/workflows/windows-node-release.yml"}]},"purpose":"beta-publish","release_id":"2026.8.1-beta.2","schema":"openclaw.release-plan.v1","tag":"v2026.8.1-beta.2","target_context_ref":"refs/tags/v2026.8.1-beta.2","tooling":{"ref":"refs/tags/release-publish/bbbbbbbbbbbb-123","repository":"openclaw/openclaw","sha":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","workflow_path":".github/workflows/full-release-validation.yml"},"validation":{"allowed_groups":["all","ci","package"],"intent":"release-beta","profile":"beta","soak":false},"version":"2026.8.1-beta.2"}
diff --git a/test/helpers/publishable-plugin-fixture.ts b/test/helpers/publishable-plugin-fixture.ts
index 947185ffd190..4bde7e7fc7a3 100644
--- a/test/helpers/publishable-plugin-fixture.ts
+++ b/test/helpers/publishable-plugin-fixture.ts
@@ -6,6 +6,7 @@ type PublishablePluginSurface = "npm" | "clawhub" | "both" | "clawhub-disabled";
 
 type PublishablePluginFixtureOptions = {
   extensionId?: string;
+  packageName?: string;
   version: string;
   publishTo: PublishablePluginSurface;
   bundledDist?: boolean;
@@ -21,7 +22,7 @@ export function writePublishablePluginFixture(
   options: PublishablePluginFixtureOptions,
 ) {
   const extensionId = options.extensionId ?? "demo-plugin";
-  const packageName = `@openclaw/${extensionId}`;
+  const packageName = options.packageName ?? `@openclaw/${extensionId}`;
   const packageDir = join(repoDir, "extensions", extensionId);
   const publishToNpm = options.publishTo === "npm" || options.publishTo === "both";
   const publishToClawHub = options.publishTo === "clawhub" || options.publishTo === "both";
diff --git a/test/plugin-clawhub-release.test.ts b/test/plugin-clawhub-release.test.ts
index f65e0df6a8e2..a53e8866f551 100644
--- a/test/plugin-clawhub-release.test.ts
+++ b/test/plugin-clawhub-release.test.ts
@@ -9,7 +9,7 @@ import {
   realpathSync,
   writeFileSync,
 } from "node:fs";
-import { delimiter, join } from "node:path";
+import { delimiter, dirname, join } from "node:path";
 import { gzipSync } from "node:zlib";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
@@ -128,6 +128,20 @@ describe("resolveChangedClawHubPublishablePluginPackages", () => {
 });
 
 describe("collectClawHubPublishablePluginPackages", () => {
+  it("rejects duplicate ClawHub package names from different plugin directories", () => {
+    const repoDir = createTempPluginRepo();
+    writePublishablePluginFixture(repoDir, {
+      extensionId: "demo-shadow",
+      packageName: "@openclaw/demo-plugin",
+      version: "2026.4.1",
+      publishTo: "clawhub",
+    });
+
+    expect(() => collectClawHubPublishablePluginPackages(repoDir)).toThrow(
+      "package @openclaw/demo-plugin is declared by multiple plugin sources: demo-plugin (extensions/demo-plugin), demo-shadow (extensions/demo-shadow).",
+    );
+  });
+
   it("requires the ClawHub external plugin contract", () => {
     const repoDir = createTempPluginRepo({
       includeClawHubContract: false,
@@ -409,6 +423,26 @@ describe("resolveSelectedClawHubPublishablePluginPackages", () => {
     expect(selected.map((plugin) => plugin.extensionId)).toEqual(["demo-plugin", "demo-two"]);
   });
 
+  it.each([
+    "packages/normalization-core/src/record-coerce.ts",
+    "packages/plugin-package-contract/src/schema.ts",
+    "scripts/lib/plugin-publication-candidates.ts",
+    "scripts/lib/plugin-publication-collector.ts",
+  ])("selects all publishable plugins when %s changes", (changedPath) => {
+    const repoDir = createTempPluginRepo({
+      extraExtensionIds: ["demo-two"],
+    });
+    const { baseRef, headRef } = commitSharedReleaseToolingChange(repoDir, changedPath);
+
+    const selected = resolveSelectedClawHubPublishablePluginPackages({
+      rootDir: repoDir,
+      plugins: collectClawHubPublishablePluginPackages(repoDir),
+      gitRange: { baseRef, headRef },
+    });
+
+    expect(selected.map((plugin) => plugin.extensionId)).toEqual(["demo-plugin", "demo-two"]);
+  });
+
   it("selects all publishable plugins when the shared setup action changes", () => {
     const repoDir = createTempPluginRepo({
       extraExtensionIds: ["demo-two"],
@@ -2153,11 +2187,18 @@ function createTempPluginRepo(
   return repoDir;
 }
 
-function commitSharedReleaseToolingChange(repoDir: string) {
+function commitSharedReleaseToolingChange(
+  repoDir: string,
+  changedPath = "scripts/plugin-clawhub-publish.sh",
+) {
   const baseRef = git(repoDir, ["rev-parse", "HEAD"]);
 
-  mkdirSync(join(repoDir, "scripts"), { recursive: true });
-  writeFileSync(join(repoDir, "scripts", "plugin-clawhub-publish.sh"), "#!/usr/bin/env bash\n");
+  const absolutePath = join(repoDir, changedPath);
+  mkdirSync(dirname(absolutePath), { recursive: true });
+  writeFileSync(
+    absolutePath,
+    changedPath.endsWith(".sh") ? "#!/usr/bin/env bash\n" : "// shared release authority\n",
+  );
   git(repoDir, ["add", "."]);
   git(repoDir, [
     "-c",
diff --git a/test/plugin-npm-release.test.ts b/test/plugin-npm-release.test.ts
index 3a12162e6d9d..f3887082299c 100644
--- a/test/plugin-npm-release.test.ts
+++ b/test/plugin-npm-release.test.ts
@@ -1,12 +1,14 @@
 // Plugin npm release tests validate plugin npm release artifacts.
-import { mkdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { bundledPluginFile, bundledPluginRoot } from "openclaw/plugin-sdk/test-fixtures";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { collectClawHubPublishablePluginPackages } from "../scripts/lib/plugin-clawhub-release.ts";
 import {
   collectChangedExtensionIdsFromPaths,
   collectPluginReleaseDependencyFreshnessErrors,
+  collectPluginNpmGitRangeSelection,
   collectPluginReleasePlan,
   collectPluginReleaseVersionFloorErrors,
   collectPublishablePluginPackages,
@@ -24,7 +26,7 @@ import { writePublishablePluginFixture } from "./helpers/publishable-plugin-fixt
 import { cleanupTempDirs, makeTempDir as makeTempRepoRoot } from "./helpers/temp-dir.js";
 import { writeJsonFile } from "./helpers/temp-repo.js";
 
-type ExecFileSync = typeof import("node:child_process").execFileSync;
+type ExecFileSync = typeof execFileSync;
 
 const childProcessMock = vi.hoisted(() => ({
   execFileSyncOverride: undefined as ExecFileSync | undefined,
@@ -32,13 +34,13 @@ const childProcessMock = vi.hoisted(() => ({
 
 vi.mock("node:child_process", async (importOriginal) => {
   const actual = await importOriginal<typeof import("node:child_process")>();
-  const execFileSync = ((...args: unknown[]) => {
+  const mockedExecFileSync = ((...args: unknown[]) => {
     const implementation = (childProcessMock.execFileSyncOverride ?? actual.execFileSync) as (
       ...args: unknown[]
     ) => unknown;
     return implementation(...args);
   }) as ExecFileSync;
-  return { ...actual, execFileSync };
+  return { ...actual, execFileSync: mockedExecFileSync };
 });
 
 const tempDirs: string[] = [];
@@ -519,6 +521,22 @@ describe("collectPluginReleasePlan", () => {
 });
 
 describe("collectPublishablePluginPackages", () => {
+  it("rejects duplicate npm package names from different plugin directories", () => {
+    const repoDir = makeTempRepoRoot(tempDirs, "openclaw-plugin-npm-release-");
+    for (const extensionId of ["demo-one", "demo-two"]) {
+      writePublishablePluginFixture(repoDir, {
+        extensionId,
+        packageName: "@openclaw/shared-plugin",
+        version: "2026.4.10",
+        publishTo: "npm",
+      });
+    }
+
+    expect(() => collectPublishablePluginPackages(repoDir)).toThrow(
+      "package @openclaw/shared-plugin is declared by multiple plugin sources: demo-one (extensions/demo-one), demo-two (extensions/demo-two).",
+    );
+  });
+
   it("defers explicitly bundled plugins from npm and ClawHub release plans", () => {
     const repoDir = makeTempRepoRoot(tempDirs, "openclaw-plugin-npm-release-");
     writePublishablePluginFixture(repoDir, {
@@ -773,6 +791,26 @@ describe("resolveSelectedPublishablePluginPackages", () => {
       }),
     ).toThrowError("Unknown or non-publishable plugin package selection: @openclaw/missing.");
   });
+
+  it("rejects duplicate selected package provenance instead of choosing the last entry", () => {
+    const firstPlugin = publishablePlugins[0];
+    if (!firstPlugin) {
+      throw new Error("publishable plugin fixture is missing");
+    }
+    expect(() =>
+      resolveSelectedPublishablePluginPackages({
+        plugins: [
+          firstPlugin,
+          {
+            ...firstPlugin,
+            extensionId: "feishu-shadow",
+            packageDir: "extensions/feishu-shadow",
+          },
+        ],
+        selection: ["@openclaw/feishu"],
+      }),
+    ).toThrow("Plugin selection has conflicting plugin package provenance");
+  });
 });
 
 describe("collectChangedExtensionIdsFromPaths", () => {
@@ -788,6 +826,71 @@ describe("collectChangedExtensionIdsFromPaths", () => {
   });
 });
 
+describe("collectPluginNpmGitRangeSelection", () => {
+  it.each([
+    ".github/actions/setup-node-env/action.yml",
+    "packages/normalization-core/src/record-coerce.ts",
+    "packages/plugin-package-contract/src/schema.ts",
+    "scripts/lib/plugin-publication-candidates.ts",
+    "scripts/lib/plugin-publication-collector.ts",
+    "scripts/plugin-npm-release-plan.ts",
+  ])("selects all publishable plugins for an authority-only %s change", (changedPath) => {
+    const repoDir = makeTempRepoRoot(tempDirs, "openclaw-plugin-npm-range-");
+    const absolutePath = join(repoDir, changedPath);
+    mkdirSync(dirname(absolutePath), { recursive: true });
+    writeFileSync(absolutePath, "// before\n");
+    execFileSync("git", ["init", "-q", "-b", "main"], { cwd: repoDir });
+    execFileSync("git", ["add", "."], { cwd: repoDir });
+    execFileSync(
+      "git",
+      [
+        "-c",
+        "user.name=OpenClaw Tests",
+        "-c",
+        "user.email=tests@openclaw.invalid",
+        "commit",
+        "-qm",
+        "base",
+      ],
+      { cwd: repoDir },
+    );
+    const baseRef = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: repoDir,
+      encoding: "utf8",
+    }).trim();
+
+    writeFileSync(absolutePath, "// after\n");
+    execFileSync("git", ["add", "."], { cwd: repoDir });
+    execFileSync(
+      "git",
+      [
+        "-c",
+        "user.name=OpenClaw Tests",
+        "-c",
+        "user.email=tests@openclaw.invalid",
+        "commit",
+        "-qm",
+        "change",
+      ],
+      { cwd: repoDir },
+    );
+    const headRef = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: repoDir,
+      encoding: "utf8",
+    }).trim();
+
+    expect(
+      collectPluginNpmGitRangeSelection({
+        rootDir: repoDir,
+        gitRange: { baseRef, headRef },
+      }),
+    ).toEqual({
+      authorityChanged: true,
+      changedExtensionIds: [],
+    });
+  });
+});
+
 describe("resolveChangedPublishablePluginPackages", () => {
   const publishablePlugins: PublishablePluginPackage[] = [
     {
diff --git a/test/scripts/plugin-npm-extended-stable-workflow.test.ts b/test/scripts/plugin-npm-extended-stable-workflow.test.ts
index 1c679ae0a5c6..3b9dc07d46c5 100644
--- a/test/scripts/plugin-npm-extended-stable-workflow.test.ts
+++ b/test/scripts/plugin-npm-extended-stable-workflow.test.ts
@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 import { parse } from "yaml";
+import { PLUGIN_NPM_RELEASE_AUTHORITY_PATHS } from "../../scripts/lib/plugin-publication-candidates.ts";
 
 const workflowPath = ".github/workflows/plugin-npm-release.yml";
 const metaPackagePath = "extensions/meta/package.json";
@@ -54,7 +55,29 @@ function step(job: Job | undefined, name: string): Step {
   return found;
 }
 
+function workflowPathPatternCovers(pattern: string, path: string): boolean {
+  if (pattern.endsWith("/**")) {
+    const directory = pattern.slice(0, -3);
+    return path === directory || path.startsWith(`${directory}/`);
+  }
+  return path === pattern;
+}
+
 describe("plugin npm extended-stable workflow", () => {
+  it("keeps push triggers aligned with npm publication authorities", () => {
+    const triggerPaths = (workflow().on?.push?.paths ?? []).filter(
+      (path) => path !== "extensions/**",
+    );
+    expect(
+      triggerPaths.map((path) => (path.endsWith("/**") ? path.slice(0, -3) : path)).toSorted(),
+    ).toEqual([...PLUGIN_NPM_RELEASE_AUTHORITY_PATHS].toSorted());
+    expect(
+      PLUGIN_NPM_RELEASE_AUTHORITY_PATHS.every((authorityPath) =>
+        triggerPaths.some((pattern) => workflowPathPatternCovers(pattern, authorityPath)),
+      ),
+    ).toBe(true);
+  });
+
   it("exposes only the default behavior and closed extended-stable override", () => {
     expect(readFileSync(workflowPath, "utf8")).toContain(
       "Plugin NPM Release [{0}] {1}', inputs.npm_dist_tag, inputs.ref",
diff --git a/test/scripts/release-plan-contract.test.ts b/test/scripts/release-plan-contract.test.ts
new file mode 100644
index 000000000000..e326dfe28cef
--- /dev/null
+++ b/test/scripts/release-plan-contract.test.ts
@@ -0,0 +1,368 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  canonicalReleasePlanJson,
+  canonicalReleasePlanLockJson,
+  createReleasePlanLock,
+  parseReleasePlanLockJson,
+  RELEASE_PLAN_CANONICALIZATION,
+  validateReleasePlan,
+} from "../../scripts/release-plan-contract.mjs";
+
+const fixtureDir = resolve("test/fixtures");
+const sourceText = readFileSync(resolve(fixtureDir, "release-plan-v1.source.json"), "utf8");
+const lockText = readFileSync(
+  resolve(fixtureDir, "release-plan-lock-v1.compatibility.json"),
+  "utf8",
+);
+const sourceFixture = JSON.parse(sourceText) as Record<string, unknown>;
+const lockFixture = JSON.parse(lockText) as Record<string, unknown>;
+
+describe("release plan contract", () => {
+  it("pins exact canonical source and lock bytes as the cross-repo golden fixture", () => {
+    expect(RELEASE_PLAN_CANONICALIZATION).toBe("ascii-sorted-compact-json-trailing-newline-v1");
+    expect(sourceText).toBe(canonicalReleasePlanJson(sourceFixture));
+    expect(lockText).toBe(canonicalReleasePlanLockJson(lockFixture));
+    expect(createReleasePlanLock(sourceFixture)).toEqual(lockFixture);
+    expect(parseReleasePlanLockJson(lockText)).toEqual(lockFixture);
+    expect(lockText.endsWith("\n")).toBe(true);
+    expect(lockText.slice(0, -1)).toMatch(/^[\x20-\x7e]+$/u);
+  });
+
+  it("rejects duplicate, reordered, pretty, CRLF, and non-ASCII lock bytes", () => {
+    const duplicate = lockText.replace(
+      '{"digest":',
+      `{"digest":"${String(lockFixture.digest)}","digest":`,
+    );
+    expect(() => parseReleasePlanLockJson(duplicate)).toThrow("duplicate key");
+    const nestedDuplicate = lockText.replace(
+      '"tooling":{"ref":',
+      '"tooling":{"ref":"ignored","\\u0072ef":',
+    );
+    expect(() => parseReleasePlanLockJson(nestedDuplicate)).toThrow("duplicate key");
+    const arrayEntryDuplicate = lockText.replace(
+      '{"name":"@openclaw/example","targets":',
+      '{"name":"ignored","name":"@openclaw/example","targets":',
+    );
+    expect(() => parseReleasePlanLockJson(arrayEntryDuplicate)).toThrow("duplicate key");
+    expect(() =>
+      parseReleasePlanLockJson(
+        `${JSON.stringify({
+          schema: lockFixture.schema,
+          plan: lockFixture.plan,
+          digest: lockFixture.digest,
+        })}\n`,
+      ),
+    ).toThrow("canonical bytes");
+    expect(() => parseReleasePlanLockJson(`${JSON.stringify(lockFixture, null, 2)}\n`)).toThrow(
+      "compact printable ASCII",
+    );
+    expect(() => parseReleasePlanLockJson(lockText.replace(/\n$/u, "\r\n"))).toThrow(
+      "exactly one trailing LF",
+    );
+    expect(() =>
+      parseReleasePlanLockJson(lockText.replace("openclaw/openclaw", "opénclaw")),
+    ).toThrow("printable ASCII");
+  });
+
+  it("rejects values that JSON.stringify would erase or coerce", () => {
+    const withUndefined = { ...sourceFixture, ignored: undefined };
+    expect(JSON.stringify(withUndefined)).toBe(JSON.stringify(sourceFixture));
+    expect(() => canonicalReleasePlanJson(withUndefined)).toThrow("unsupported undefined");
+
+    const withNan = { ...sourceFixture, tag: Number.NaN };
+    expect(JSON.stringify(withNan)).toBe(JSON.stringify({ ...sourceFixture, tag: null }));
+    expect(() => canonicalReleasePlanJson(withNan)).toThrow("must be finite");
+
+    for (const value of [
+      Number.POSITIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+      () => undefined,
+      Symbol("ignored"),
+      1n,
+    ]) {
+      expect(() => canonicalReleasePlanJson({ ...sourceFixture, ignored: value })).toThrow(
+        "canonical JSON",
+      );
+    }
+    expect(() => canonicalReleasePlanJson({ ...sourceFixture, ignored: -0 })).toThrow(
+      "negative zero",
+    );
+  });
+
+  it("rejects non-tree and non-data JSON structures", () => {
+    const sparseGroups = ["all", , "package"];
+    expect(JSON.stringify(sparseGroups)).toBe('["all",null,"package"]');
+    expect(() =>
+      canonicalReleasePlanJson({
+        ...sourceFixture,
+        validation: {
+          ...(sourceFixture.validation as Record<string, unknown>),
+          allowed_groups: sparseGroups,
+        },
+      }),
+    ).toThrow("must be dense");
+
+    const augmentedGroups = ["all", "ci", "package"];
+    Object.defineProperty(augmentedGroups, "metadata", { enumerable: true, value: "ignored" });
+    expect(() =>
+      canonicalReleasePlanJson({
+        ...sourceFixture,
+        validation: {
+          ...(sourceFixture.validation as Record<string, unknown>),
+          allowed_groups: augmentedGroups,
+        },
+      }),
+    ).toThrow("no extra properties");
+
+    const cyclic = { ...sourceFixture } as Record<string, unknown>;
+    cyclic.self = cyclic;
+    expect(() => canonicalReleasePlanJson(cyclic)).toThrow("must not contain cycles");
+
+    const nonPlain = Object.assign(new (class ReleasePlan {})(), sourceFixture);
+    expect(() => canonicalReleasePlanJson(nonPlain)).toThrow("must be plain");
+
+    const accessor = { ...sourceFixture };
+    Object.defineProperty(accessor, "hidden", {
+      enumerable: true,
+      get: () => "ignored",
+    });
+    expect(() => canonicalReleasePlanJson(accessor)).toThrow("enumerable data properties");
+
+    const symbolKey = { ...sourceFixture, [Symbol("ignored")]: true };
+    expect(() => canonicalReleasePlanJson(symbolKey)).toThrow("must use string keys");
+  });
+
+  it("enforces the purpose, version, tag, and target context matrix", () => {
+    expect(() =>
+      validateReleasePlan({
+        ...sourceFixture,
+        purpose: "stable-publish",
+        validation: {
+          allowed_groups: ["all", "ci", "package"],
+          intent: "release-stable",
+          profile: "stable",
+          soak: true,
+        },
+      }),
+    ).toThrow("stable-publish release plan version must be stable");
+    expect(() =>
+      validateReleasePlan({
+        ...sourceFixture,
+        purpose: "main-qualification",
+        tag: null,
+        target_context_ref: "refs/tags/null",
+        validation: {
+          allowed_groups: ["all", "ci", "package"],
+          intent: "main-weekly",
+          profile: "full",
+          soak: true,
+        },
+      }),
+    ).toThrow("candidate SHA context");
+    expect(() =>
+      validateReleasePlan({
+        ...sourceFixture,
+        tag: "v2026.8.1-beta.3",
+      }),
+    ).toThrow("exact version tag context");
+  });
+
+  it("binds purpose, intent, profile, and soak to one authoritative policy", () => {
+    expect(() =>
+      validateReleasePlan({
+        ...sourceFixture,
+        validation: {
+          ...(sourceFixture.validation as Record<string, unknown>),
+          intent: "release-stable",
+        },
+      }),
+    ).toThrow("beta-publish does not allow validation intent");
+    expect(() =>
+      validateReleasePlan({
+        ...sourceFixture,
+        validation: {
+          ...(sourceFixture.validation as Record<string, unknown>),
+          profile: "full",
+        },
+      }),
+    ).toThrow("profile assertion conflicts");
+    expect(() =>
+      validateReleasePlan({
+        ...sourceFixture,
+        validation: {
+          ...(sourceFixture.validation as Record<string, unknown>),
+          soak: true,
+        },
+      }),
+    ).toThrow("soak assertion conflicts");
+  });
+
+  it("accepts daily and weekly main qualification intents", () => {
+    const mainPlan = {
+      ...sourceFixture,
+      purpose: "main-qualification",
+      tag: null,
+      target_context_ref: sourceFixture.candidate_sha,
+    };
+    expect(
+      validateReleasePlan({
+        ...mainPlan,
+        validation: {
+          allowed_groups: ["all", "ci", "package"],
+          intent: "main-daily",
+          profile: "beta",
+          soak: false,
+        },
+      }).validation.intent,
+    ).toBe("main-daily");
+    expect(
+      validateReleasePlan({
+        ...mainPlan,
+        validation: {
+          allowed_groups: ["all", "ci", "package"],
+          intent: "main-weekly",
+          profile: "full",
+          soak: true,
+        },
+      }).validation.intent,
+    ).toBe("main-weekly");
+  });
+
+  it("keeps diagnostic plans tagless, non-publishable, and distinct from qualification", () => {
+    const diagnosticPlan = validateReleasePlan({
+      ...sourceFixture,
+      purpose: "diagnostic",
+      tag: null,
+      target_context_ref: sourceFixture.candidate_sha,
+      tooling: {
+        ...(sourceFixture.tooling as Record<string, unknown>),
+        ref: "refs/heads/main",
+      },
+      validation: {
+        allowed_groups: ["all", "ci", "package"],
+        intent: "diagnostic-full",
+        profile: "full",
+        soak: true,
+      },
+    });
+    expect(diagnosticPlan).toMatchObject({
+      purpose: "diagnostic",
+      tag: null,
+      target_context_ref: sourceFixture.candidate_sha,
+      validation: {
+        intent: "diagnostic-full",
+        profile: "full",
+        soak: true,
+      },
+    });
+    expect(diagnosticPlan.purpose).not.toBe("main-qualification");
+    expect(diagnosticPlan.purpose).not.toBe("postpublish-confidence");
+
+    expect(() =>
+      validateReleasePlan({
+        ...diagnosticPlan,
+        tag: sourceFixture.tag,
+        target_context_ref: sourceFixture.target_context_ref,
+      }),
+    ).toThrow("diagnostic release plans require a null tag and candidate SHA context");
+    expect(() =>
+      validateReleasePlan({
+        ...diagnosticPlan,
+        validation: {
+          ...diagnosticPlan.validation,
+          intent: "release-beta",
+          profile: "beta",
+          soak: false,
+        },
+      }),
+    ).toThrow("diagnostic does not allow validation intent");
+    expect(() =>
+      validateReleasePlan({
+        ...diagnosticPlan,
+        tooling: {
+          ...diagnosticPlan.tooling,
+          ref: "refs/heads/feature",
+        },
+      }),
+    ).toThrow("diagnostic tooling must use trusted main or a protected release-publish tag");
+  });
+
+  it("rejects unknown authority, invalid ordering, and unsupported versions", () => {
+    expect(() => validateReleasePlan({ ...sourceFixture, run_id: "123" })).toThrow(
+      "release plan keys must be exactly",
+    );
+    expect(() =>
+      validateReleasePlan({
+        ...sourceFixture,
+        version: "2026.08.1-beta.2",
+        release_id: "2026.08.1-beta.2",
+        tag: "v2026.08.1-beta.2",
+        target_context_ref: "refs/tags/v2026.08.1-beta.2",
+      }),
+    ).toThrow("supported release version");
+    expect(() =>
+      validateReleasePlan({
+        ...sourceFixture,
+        inventory: {
+          ...(sourceFixture.inventory as Record<string, unknown>),
+          packages: [
+            { name: "openclaw", targets: ["npm"], version: "2026.8.1-beta.2" },
+            {
+              name: "@openclaw/example",
+              targets: ["clawhub", "npm"],
+              version: "2026.8.1-beta.2",
+            },
+          ],
+        },
+      }),
+    ).toThrow("ascending ASCII order");
+  });
+
+  it("rejects arbitrary tooling routes", () => {
+    expect(() =>
+      validateReleasePlan({
+        ...sourceFixture,
+        tooling: {
+          ...(sourceFixture.tooling as Record<string, unknown>),
+          ref: "refs/heads/main",
+        },
+      }),
+    ).toThrow("protected release-publish tag");
+    expect(() =>
+      validateReleasePlan({
+        ...sourceFixture,
+        tooling: {
+          ...(sourceFixture.tooling as Record<string, unknown>),
+          ref: "refs/tags/release-publish/cccccccccccc-123",
+        },
+      }),
+    ).toThrow("bound to its SHA");
+    expect(() =>
+      validateReleasePlan({
+        ...sourceFixture,
+        purpose: "main-qualification",
+        tag: null,
+        target_context_ref: sourceFixture.candidate_sha,
+        tooling: {
+          ...(sourceFixture.tooling as Record<string, unknown>),
+          ref: "refs/heads/feature",
+        },
+        validation: {
+          allowed_groups: ["all", "ci", "package"],
+          intent: "main-weekly",
+          profile: "full",
+          soak: true,
+        },
+      }),
+    ).toThrow("trusted main");
+  });
+
+  it("keeps run and rerun state outside ReleasePlan", () => {
+    const plan = validateReleasePlan(sourceFixture);
+    expect(plan).not.toHaveProperty("run_id");
+    expect(plan).not.toHaveProperty("rerun_group");
+    expect(plan).not.toHaveProperty("filters");
+  });
+});
diff --git a/test/scripts/release-plan-producer.test.ts b/test/scripts/release-plan-producer.test.ts
new file mode 100644
index 000000000000..a74bbabd774f
--- /dev/null
+++ b/test/scripts/release-plan-producer.test.ts
@@ -0,0 +1,1201 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  linkSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { parse } from "yaml";
+import { collectClawHubPublishablePluginPackages } from "../../scripts/lib/plugin-clawhub-release.ts";
+import { collectPublishablePluginPackages } from "../../scripts/lib/plugin-npm-release.ts";
+import {
+  canonicalReleasePlanLockJson,
+  createReleasePlanLock,
+  type ReleasePlan,
+  type ReleasePlanLock,
+} from "../../scripts/release-plan-contract.mjs";
+import {
+  deriveReleasePlanPolicy,
+  runReleasePlanProducerOperation,
+} from "../../scripts/release-plan-producer-core.mts";
+import {
+  produceReleasePlan as trustedCheckoutProduceReleasePlan,
+  verifyReleasePlanLock as trustedCheckoutVerifyReleasePlanLock,
+  type MainQualificationValidationIntent,
+  type ReleasePlanIntent,
+  type ReleasePlanSource,
+} from "../../scripts/release-plan-producer.mts";
+import { writePublishablePluginFixture } from "../helpers/publishable-plugin-fixture.js";
+import { useAutoCleanupTempDirTracker } from "../helpers/temp-dir.js";
+
+const tempDirs = useAutoCleanupTempDirTracker(afterEach);
+const TOOLING_CLOSURE = [
+  "packages/normalization-core/src/record-coerce.ts",
+  "packages/normalization-core/src/string-coerce.ts",
+  "packages/plugin-package-contract/src/index.ts",
+  "scripts/release-plan-producer.mts",
+  "scripts/release-plan-producer-core.mts",
+  "scripts/release-plan-contract.mjs",
+  "scripts/release-validation-intent.mjs",
+  "scripts/release-tooling-identity.mjs",
+  "scripts/lib/npm-publish-plan.mjs",
+  "scripts/lib/plugin-publication-candidates.ts",
+  "scripts/lib/plugin-publication-collector.ts",
+  "scripts/lib/record-shared.mjs",
+  "scripts/lib/release-version.mjs",
+];
+const TOOLING_ROOT_FILES = ["package.json", "pnpm-lock.yaml"];
+
+function writeFixture(root: string, path: string, content: string) {
+  const target = join(root, path);
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content);
+}
+
+function commit(root: string, message: string, options: { allowEmpty?: boolean } = {}): string {
+  execFileSync("git", ["add", "."], { cwd: root });
+  execFileSync(
+    "git",
+    [
+      "-c",
+      "user.name=OpenClaw Test",
+      "-c",
+      "user.email=test@example.invalid",
+      "commit",
+      "-q",
+      ...(options.allowEmpty ? ["--allow-empty"] : []),
+      "-m",
+      message,
+    ],
+    { cwd: root },
+  );
+  return execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" }).trim();
+}
+
+function copyToolingClosure(root: string) {
+  for (const path of [...TOOLING_CLOSURE, ...TOOLING_ROOT_FILES]) {
+    writeFixture(root, path, readFileSync(resolve(path), "utf8"));
+  }
+}
+
+function createFixtureRepo(
+  version = "2026.8.1-beta.2",
+  options: {
+    conflictingPlatformId?: boolean;
+    corePackageNameCollision?: boolean;
+    duplicateCrossTargetPackageName?: boolean;
+    malformedPlugin?: boolean;
+    malformedPluginJson?: boolean;
+  } = {},
+) {
+  const root = tempDirs.make("openclaw-release-plan-");
+  execFileSync("git", ["init", "-q", "-b", "tooling"], { cwd: root });
+
+  writeFixture(
+    root,
+    "package.json",
+    JSON.stringify({
+      name: "openclaw",
+      version,
+      dependencies: { "@openclaw/ai": "workspace:*" },
+    }),
+  );
+  for (const [path, name] of [
+    ["packages/ai", "@openclaw/ai"],
+    ["packages/gateway-client", "@openclaw/gateway-client"],
+    ["packages/gateway-protocol", "@openclaw/gateway-protocol"],
+  ]) {
+    writeFixture(
+      root,
+      `${path}/package.json`,
+      JSON.stringify({
+        name,
+        version,
+        openclaw: { release: { publishToNpm: true } },
+      }),
+    );
+  }
+  if (options.corePackageNameCollision) {
+    writePublishablePluginFixture(root, {
+      extensionId: "shadow-ai",
+      packageName: "@openclaw/ai",
+      version,
+      publishTo: "both",
+    });
+  } else if (options.duplicateCrossTargetPackageName) {
+    writePublishablePluginFixture(root, {
+      extensionId: "duplicate-npm",
+      packageName: "@openclaw/duplicate",
+      version,
+      publishTo: "npm",
+    });
+    writePublishablePluginFixture(root, {
+      extensionId: "duplicate-clawhub",
+      packageName: "@openclaw/duplicate",
+      version,
+      publishTo: "clawhub",
+    });
+  } else if (options.malformedPluginJson) {
+    writeFixture(root, "extensions/broken/package.json", "{ not-json\n");
+  } else if (options.malformedPlugin) {
+    writeFixture(
+      root,
+      "extensions/broken/package.json",
+      JSON.stringify({
+        name: "@openclaw/broken",
+        version,
+        type: "commonjs",
+        private: true,
+        repository: { type: "git", url: "https://github.com/openclaw/openclaw" },
+        openclaw: {
+          extensions: ["./index.ts"],
+          compat: { pluginApi: `>=${version}` },
+          build: { openclawVersion: version },
+          install: { npmSpec: "@openclaw/broken" },
+          release: { publishToNpm: true },
+        },
+      }),
+    );
+  }
+  const candidateSha = commit(root, "candidate");
+  const candidateRef = `refs/tags/v${version}`;
+
+  writeFixture(
+    root,
+    ".github/workflows/full-release-validation.yml",
+    [
+      "on:",
+      "  workflow_dispatch:",
+      "    inputs:",
+      "      rerun_group:",
+      "        options:",
+      "          - package",
+      "          - all",
+      "          - ci",
+      "",
+    ].join("\n"),
+  );
+  writeFixture(
+    root,
+    ".github/workflows/openclaw-release-publish.yml",
+    [
+      "name: Release Publish",
+      "jobs:",
+      "  publish:",
+      "    runs-on: ubuntu-latest",
+      "    steps:",
+      "      - run: |",
+      "          promote_windows_release_assets() {",
+      "            dispatch_workflow windows-node-release.yml",
+      "          }",
+      "          promote_android_release_asset() {",
+      '            dispatch_workflow_at_ref "${RELEASE_TAG}" "${TARGET_SHA}" android-release.yml',
+      "          }",
+      "          dispatch_workflow plugin-npm-release.yml",
+      "  publish_docker:",
+      "    uses: ./.github/workflows/docker-release.yml",
+      "  publish_vcr:",
+      "    uses: ./.github/workflows/vercel-container-registry-publish.yml",
+      ...(options.conflictingPlatformId
+        ? ["  publish_windows:", "    uses: ./.github/workflows/docker-release.yml"]
+        : []),
+      "",
+    ].join("\n"),
+  );
+  writeFixture(
+    root,
+    ".github/workflows/openclaw-npm-release.yml",
+    [
+      "name: NPM Release",
+      "jobs:",
+      "  preflight:",
+      "    steps:",
+      "      - name: Pack publishable core packages",
+      "        env:",
+      "          CORE_PACKAGE_DIRS: packages/ai packages/gateway-protocol packages/gateway-client",
+      "        run: |",
+      '          if [[ "$package_dir" == "packages/ai" ]] && ! node -e \'const pkg = require("./package.json"); process.exit(pkg.dependencies?.["@openclaw/ai"] ? 0 : 1)\'; then',
+      "            exit 0",
+      "          fi",
+      "",
+    ].join("\n"),
+  );
+  for (const name of [
+    "android-release.yml",
+    "docker-release.yml",
+    "plugin-npm-release.yml",
+    "vercel-container-registry-publish.yml",
+    "windows-node-release.yml",
+  ]) {
+    writeFixture(root, `.github/workflows/${name}`, `name: ${name}\n`);
+  }
+  copyToolingClosure(root);
+  const toolingSha = commit(root, "tooling");
+  const toolingFullRef = `refs/tags/release-publish/${toolingSha.slice(0, 12)}-1`;
+  return { candidateRef, candidateSha, root, toolingFullRef, toolingSha };
+}
+
+function sourceParams(
+  fixture: ReturnType<typeof createFixtureRepo>,
+  intent: ReleasePlanIntent = "publish",
+  validationIntent?: MainQualificationValidationIntent,
+): ReleasePlanSource {
+  const source = {
+    repoRoot: fixture.root,
+    candidateSha: fixture.candidateSha,
+    candidateRef:
+      intent === "diagnostic" || intent === "main-qualification"
+        ? fixture.candidateSha
+        : fixture.candidateRef,
+    toolingSha: fixture.toolingSha,
+    toolingFullRef: fixture.toolingFullRef,
+    runGh: trustedToolingGh(fixture.toolingFullRef, fixture.toolingSha),
+  };
+  return (
+    intent === "main-qualification"
+      ? { ...source, intent, validationIntent }
+      : { ...source, intent }
+  ) as ReleasePlanSource;
+}
+
+function trustedToolingGh(toolingFullRef: string, toolingSha: string) {
+  return (args: string[]) => {
+    const endpoint = args[1];
+    if (
+      endpoint ===
+      `repos/openclaw/openclaw/git/ref/tags/${toolingFullRef.slice("refs/tags/".length)}`
+    ) {
+      return JSON.stringify({
+        ref: toolingFullRef,
+        object: { type: "commit", sha: toolingSha },
+      });
+    }
+    throw new Error(`unexpected GitHub API request: ${args.join(" ")}`);
+  };
+}
+
+function runCoreOperation(
+  request:
+    | { operation: "produce"; params: ReleasePlanSource }
+    | { operation: "verify-lock"; lockJson: string; params: ReleasePlanSource },
+) {
+  const { runGh, ...params } = request.params;
+  return runReleasePlanProducerOperation(
+    { ...request, params },
+    {
+      runGh:
+        runGh ??
+        (() => {
+          throw new Error("unexpected GitHub API request");
+        }),
+      parseYamlDocuments: (sources) =>
+        sources.map((source) => parse(source)) as [unknown, unknown, unknown],
+    },
+  );
+}
+
+function produceReleasePlan(params: ReleasePlanSource) {
+  return runCoreOperation({ operation: "produce", params }) as ReleasePlan;
+}
+
+function verifyReleasePlanLock(lockJson: string, params: ReleasePlanSource) {
+  return runCoreOperation({ operation: "verify-lock", lockJson, params }) as ReleasePlanLock;
+}
+
+type YamlPackageHarnessParams = {
+  fixture: ReturnType<typeof createFixtureRepo>;
+  packageRoot: string;
+  sentinelPath: string;
+  tempRoot: string;
+};
+
+function runYamlPackageSubprocess(
+  options: {
+    beforeProduce?: (params: YamlPackageHarnessParams) => string;
+    environment?: (params: YamlPackageHarnessParams) => Record<string, string>;
+    mutate?: (params: YamlPackageHarnessParams) => void;
+    mutateTooling?: (fixture: ReturnType<typeof createFixtureRepo>) => void;
+    beforeImport?: (params: YamlPackageHarnessParams) => string;
+    executionHead?: (fixture: ReturnType<typeof createFixtureRepo>) => string;
+    remoteToolingSha?: (params: YamlPackageHarnessParams) => string;
+  } = {},
+) {
+  let fixture = createFixtureRepo();
+  if (options.mutateTooling) {
+    options.mutateTooling(fixture);
+    const toolingSha = commit(fixture.root, "mutated tooling");
+    fixture = {
+      ...fixture,
+      toolingSha,
+      toolingFullRef: `refs/tags/release-publish/${toolingSha.slice(0, 12)}-2`,
+    };
+  }
+  const packageRoot = join(fixture.root, "node_modules/yaml");
+  cpSync(realpathSync(resolve("node_modules/yaml")), packageRoot, { recursive: true });
+  const sentinelPath = join(fixture.root, "yaml-executed");
+  const tempRoot = join(fixture.root, "yaml-temp");
+  mkdirSync(tempRoot);
+  const params = { fixture, packageRoot, sentinelPath, tempRoot };
+  options.mutate?.(params);
+  writeFixture(
+    fixture.root,
+    "yaml-package-harness.mts",
+    `
+${options.beforeImport?.(params) ?? ""}
+const { produceReleasePlan } = await import("./scripts/release-plan-producer.mts");
+${options.beforeProduce?.(params) ?? ""}
+
+const toolingFullRef = ${JSON.stringify(fixture.toolingFullRef)};
+const toolingSha = ${JSON.stringify(fixture.toolingSha)};
+produceReleasePlan({
+  repoRoot: ${JSON.stringify(fixture.root)},
+  intent: "publish",
+  candidateSha: ${JSON.stringify(fixture.candidateSha)},
+  candidateRef: ${JSON.stringify(fixture.candidateRef)},
+  toolingSha,
+  toolingFullRef,
+  runGh: () => JSON.stringify({
+    ref: toolingFullRef,
+    object: { type: "commit", sha: ${JSON.stringify(options.remoteToolingSha?.(params) ?? fixture.toolingSha)} },
+  }),
+});
+const moduleApi = await import("node:module");
+const harnessRequire = moduleApi.createRequire(import.meta.url);
+const leakedSnapshotCache = Object.keys(harnessRequire.cache).filter(path =>
+  path.includes("openclaw-release-yaml-")
+);
+if (leakedSnapshotCache.length > 0) {
+  throw new Error("verified yaml snapshot leaked into parent require.cache");
+}
+    `,
+  );
+  if (options.executionHead) {
+    execFileSync("git", ["update-ref", "HEAD", options.executionHead(fixture)], {
+      cwd: fixture.root,
+    });
+  }
+  return {
+    result: spawnSync(process.execPath, [join(fixture.root, "yaml-package-harness.mts")], {
+      cwd: fixture.root,
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        TMPDIR: tempRoot,
+        ...options.environment?.(params),
+      },
+    }),
+    fixture,
+    packageRoot,
+    sentinelPath,
+    tempRoot,
+  };
+}
+
+function yamlTempEntries(root: string) {
+  return readdirSync(root).filter((name) => name.startsWith("openclaw-release-yaml-"));
+}
+
+describe("release plan producer", () => {
+  it("rejects invalid identity through the verified child dispatcher", () => {
+    expect(() =>
+      runReleasePlanProducerOperation(
+        {
+          operation: "produce",
+          params: {
+            candidateRef: "refs/tags/v2026.8.1-beta.2",
+            candidateSha: "not-a-sha",
+            intent: "publish",
+            toolingFullRef: "refs/heads/main",
+            toolingSha: "f".repeat(40),
+          },
+        },
+        {
+          parseYamlDocuments: () => [{}, {}, {}],
+          runGh: () => {
+            throw new Error("unexpected GitHub request");
+          },
+        },
+      ),
+    ).toThrow("candidate SHA must be an exact lowercase 40-character commit SHA");
+  });
+
+  it("derives purpose, profile, tag, and soak from the canonical version parser", () => {
+    expect(deriveReleasePlanPolicy("publish", "2026.8.1-beta.2")).toEqual({
+      intent: "release-beta",
+      profile: "beta",
+      publishable: true,
+      purpose: "beta-publish",
+      soak: false,
+      tag: "v2026.8.1-beta.2",
+    });
+    expect(deriveReleasePlanPolicy("publish", "2026.8.1")).toEqual({
+      intent: "release-stable",
+      profile: "stable",
+      publishable: true,
+      purpose: "stable-publish",
+      soak: true,
+      tag: "v2026.8.1",
+    });
+    expect(deriveReleasePlanPolicy("postpublish-confidence", "2026.8.1-beta.2")).toEqual({
+      intent: "diagnostic-full",
+      profile: "full",
+      publishable: false,
+      purpose: "postpublish-confidence",
+      soak: true,
+      tag: "v2026.8.1-beta.2",
+    });
+    expect(deriveReleasePlanPolicy("diagnostic", "2026.8.1-beta.2")).toEqual({
+      intent: "diagnostic-full",
+      profile: "full",
+      publishable: false,
+      purpose: "diagnostic",
+      soak: true,
+      tag: null,
+    });
+    expect(() => deriveReleasePlanPolicy("main-qualification", "2026.8.1-beta.2")).toThrow(
+      "requires an explicit validation intent",
+    );
+    expect(deriveReleasePlanPolicy("main-qualification", "2026.8.1-beta.2", "main-daily")).toEqual({
+      intent: "main-daily",
+      profile: "beta",
+      publishable: false,
+      purpose: "main-qualification",
+      soak: false,
+      tag: null,
+    });
+    expect(deriveReleasePlanPolicy("main-qualification", "2026.8.1-beta.2", "main-weekly")).toEqual(
+      {
+        intent: "main-weekly",
+        profile: "full",
+        publishable: false,
+        purpose: "main-qualification",
+        soak: true,
+        tag: null,
+      },
+    );
+    expect(() => deriveReleasePlanPolicy("publish", "2026.08.1")).toThrow(
+      "unsupported release version",
+    );
+    expect(() =>
+      deriveReleasePlanPolicy("unexpected" as ReleasePlanIntent, "2026.8.1-beta.2"),
+    ).toThrow("unsupported release plan intent");
+  });
+
+  it("reads candidate inventory and tooling policy from genuinely different commits", () => {
+    const fixture = createFixtureRepo();
+    expect(fixture.candidateSha).not.toBe(fixture.toolingSha);
+    expect(() =>
+      execFileSync("git", ["cat-file", "-e", fixture.candidateRef], {
+        cwd: fixture.root,
+        stdio: "ignore",
+      }),
+    ).toThrow();
+    expect(() =>
+      execFileSync(
+        "git",
+        ["cat-file", "-e", `${fixture.candidateSha}:scripts/release-plan-producer.mts`],
+        { cwd: fixture.root, stdio: "ignore" },
+      ),
+    ).toThrow();
+    expect(
+      execFileSync(
+        "git",
+        ["cat-file", "-e", `${fixture.toolingSha}:scripts/release-plan-producer.mts`],
+        { cwd: fixture.root, stdio: "ignore" },
+      ),
+    ).toBeNull();
+    expect(() =>
+      execFileSync("git", ["cat-file", "-e", fixture.toolingFullRef], {
+        cwd: fixture.root,
+        stdio: "ignore",
+      }),
+    ).toThrow();
+
+    const plan = produceReleasePlan(sourceParams(fixture));
+    expect(plan).toMatchObject({
+      candidate_sha: fixture.candidateSha,
+      purpose: "beta-publish",
+      release_id: "2026.8.1-beta.2",
+      tag: "v2026.8.1-beta.2",
+      target_context_ref: fixture.candidateRef,
+      version: "2026.8.1-beta.2",
+    });
+    expect(plan.tooling).toMatchObject({
+      ref: fixture.toolingFullRef,
+      sha: fixture.toolingSha,
+    });
+    expect(plan.validation).toEqual({
+      allowed_groups: ["all", "ci", "package"],
+      intent: "release-beta",
+      profile: "beta",
+      soak: false,
+    });
+    expect(plan.inventory.packages).toEqual([
+      { name: "@openclaw/ai", targets: ["npm"], version: "2026.8.1-beta.2" },
+      { name: "@openclaw/gateway-client", targets: ["npm"], version: "2026.8.1-beta.2" },
+      { name: "@openclaw/gateway-protocol", targets: ["npm"], version: "2026.8.1-beta.2" },
+      { name: "openclaw", targets: ["npm"], version: "2026.8.1-beta.2" },
+    ]);
+    expect(plan.inventory.platforms).toEqual([
+      { id: "android", source: ".github/workflows/android-release.yml" },
+      { id: "docker", source: ".github/workflows/docker-release.yml" },
+      {
+        id: "vcr",
+        source: ".github/workflows/vercel-container-registry-publish.yml",
+      },
+      { id: "windows", source: ".github/workflows/windows-node-release.yml" },
+    ]);
+  });
+
+  it("requires the final tag only for postpublish confidence", () => {
+    const fixture = createFixtureRepo();
+    expect(produceReleasePlan(sourceParams(fixture))).toMatchObject({
+      purpose: "beta-publish",
+      target_context_ref: fixture.candidateRef,
+    });
+    expect(() => produceReleasePlan(sourceParams(fixture, "postpublish-confidence"))).toThrow(
+      "published candidate tag does not resolve",
+    );
+
+    execFileSync(
+      "git",
+      ["tag", fixture.candidateRef.slice("refs/tags/".length), fixture.candidateSha],
+      {
+        cwd: fixture.root,
+      },
+    );
+    expect(produceReleasePlan(sourceParams(fixture, "postpublish-confidence"))).toMatchObject({
+      purpose: "postpublish-confidence",
+      target_context_ref: fixture.candidateRef,
+      validation: {
+        intent: "diagnostic-full",
+        profile: "full",
+        soak: true,
+      },
+    });
+  });
+
+  it("produces tagless diagnostics from trusted main or protected tooling", () => {
+    const fixture = createFixtureRepo();
+    expect(produceReleasePlan(sourceParams(fixture, "diagnostic"))).toMatchObject({
+      candidate_sha: fixture.candidateSha,
+      purpose: "diagnostic",
+      tag: null,
+      target_context_ref: fixture.candidateSha,
+      tooling: {
+        ref: fixture.toolingFullRef,
+        sha: fixture.toolingSha,
+      },
+      validation: {
+        intent: "diagnostic-full",
+        profile: "full",
+        soak: true,
+      },
+    });
+
+    expect(
+      produceReleasePlan({
+        ...sourceParams(fixture, "diagnostic"),
+        toolingFullRef: "refs/heads/main",
+        runGh: (args) => {
+          expect(args[1]).toBe(`repos/openclaw/openclaw/compare/${fixture.toolingSha}...main`);
+          return JSON.stringify({ status: "identical" });
+        },
+      }),
+    ).toMatchObject({
+      purpose: "diagnostic",
+      tag: null,
+      target_context_ref: fixture.candidateSha,
+      tooling: {
+        ref: "refs/heads/main",
+        sha: fixture.toolingSha,
+      },
+    });
+  });
+
+  it("requires main qualification producers to choose daily or weekly", () => {
+    const fixture = createFixtureRepo();
+    expect(() => produceReleasePlan(sourceParams(fixture, "main-qualification"))).toThrow(
+      "requires an explicit validation intent",
+    );
+    expect(
+      produceReleasePlan(sourceParams(fixture, "main-qualification", "main-daily")).validation,
+    ).toMatchObject({
+      intent: "main-daily",
+      profile: "beta",
+      soak: false,
+    });
+    expect(
+      produceReleasePlan(sourceParams(fixture, "main-qualification", "main-weekly")).validation,
+    ).toMatchObject({
+      intent: "main-weekly",
+      profile: "full",
+      soak: true,
+    });
+  });
+
+  it("requires exact candidate and tooling identity instead of checkout HEAD", () => {
+    const fixture = createFixtureRepo();
+    expect(() =>
+      produceReleasePlan({ ...sourceParams(fixture), candidateSha: "f".repeat(40) }),
+    ).toThrow("candidate SHA does not resolve");
+    expect(() =>
+      produceReleasePlan({
+        ...sourceParams(fixture),
+        runGh: trustedToolingGh(fixture.toolingFullRef, fixture.candidateSha),
+      }),
+    ).toThrow(
+      "protected release tooling tag is missing, moved, annotated, or bound to the wrong SHA",
+    );
+    expect(() =>
+      produceReleasePlan({ ...sourceParams(fixture), candidateRef: "refs/heads/tooling" }),
+    ).toThrow("candidate ref must be");
+  });
+
+  it("rejects a locally forged protected tooling tag that GitHub does not own", () => {
+    const fixture = createFixtureRepo();
+    const forgedFullRef = `refs/tags/release-publish/${fixture.toolingSha.slice(0, 12)}-999`;
+    execFileSync("git", ["tag", forgedFullRef.slice("refs/tags/".length), fixture.toolingSha], {
+      cwd: fixture.root,
+    });
+
+    expect(() =>
+      produceReleasePlan({
+        ...sourceParams(fixture),
+        toolingFullRef: forgedFullRef,
+        runGh: () => {
+          throw new Error("HTTP 404");
+        },
+      }),
+    ).toThrow("protected release tooling tag is missing or unreadable");
+  });
+
+  it("rejects a caller producer that differs from the exact tooling commit", () => {
+    const { result } = runYamlPackageSubprocess({
+      mutate: ({ fixture }) => {
+        const producerPath = join(fixture.root, "scripts/release-plan-producer.mts");
+        writeFileSync(producerPath, `${readFileSync(producerPath, "utf8")}\n// ambient mismatch\n`);
+      },
+    });
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain("tooling bootstrap differs from tooling SHA");
+  });
+
+  it("rejects a byte-identical bootstrap launched from the candidate checkout", () => {
+    const { result, sentinelPath } = runYamlPackageSubprocess({
+      executionHead: (fixture) => fixture.candidateSha,
+    });
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain("tooling bootstrap checkout HEAD must equal tooling SHA");
+    expect(existsSync(sentinelPath)).toBe(false);
+  });
+
+  it("exports bootstrap operations for trusted-checkout callers", () => {
+    expect(trustedCheckoutProduceReleasePlan).toBeTypeOf("function");
+    expect(trustedCheckoutVerifyReleasePlanLock).toBeTypeOf("function");
+  });
+
+  it("rejects a forged remote tooling SHA before executing ambient tooling", () => {
+    const { result, sentinelPath } = runYamlPackageSubprocess({
+      mutate: ({ fixture, sentinelPath: sentinel }) => {
+        writeFixture(
+          fixture.root,
+          "scripts/release-plan-producer-core.mts",
+          `require("node:fs").writeFileSync(${JSON.stringify(sentinel)}, "ambient-core");\n`,
+        );
+      },
+      remoteToolingSha: ({ fixture }) => fixture.candidateSha,
+    });
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain(
+      "protected release tooling tag is missing, moved, annotated, or bound to the wrong SHA",
+    );
+    expect(existsSync(sentinelPath)).toBe(false);
+  });
+
+  it("ignores uncommitted ambient tooling after verifying the exact tooling commit", () => {
+    const { result, sentinelPath } = runYamlPackageSubprocess({
+      mutate: ({ fixture, sentinelPath: sentinel }) => {
+        writeFixture(
+          fixture.root,
+          "scripts/release-plan-producer-core.mts",
+          `require("node:fs").writeFileSync(${JSON.stringify(sentinel)}, "ambient-core");\n`,
+        );
+      },
+    });
+    expect(result.status).toBe(0);
+    expect(existsSync(sentinelPath)).toBe(false);
+  });
+
+  it("rejects a symlinked tooling closure before executing its target", () => {
+    const { result, sentinelPath } = runYamlPackageSubprocess({
+      mutateTooling: (fixture) => {
+        const targetPath = join(fixture.root, "scripts/release-plan-producer-core.mts");
+        const sentinelTarget = join(fixture.root, "scripts/release-plan-producer-evil.mts");
+        writeFileSync(
+          sentinelTarget,
+          `require("node:fs").writeFileSync(${JSON.stringify(join(fixture.root, "yaml-executed"))}, "linked-core");\n`,
+        );
+        unlinkSync(targetPath);
+        symlinkSync("release-plan-producer-evil.mts", targetPath);
+      },
+    });
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain("tooling closure path must be a regular Git blob");
+    expect(existsSync(sentinelPath)).toBe(false);
+  });
+
+  it("rejects package imports in the retained tooling closure before execution", () => {
+    const { result, sentinelPath } = runYamlPackageSubprocess({
+      mutateTooling: (fixture) => {
+        const corePath = join(fixture.root, "scripts/release-plan-producer-core.mts");
+        writeFileSync(
+          corePath,
+          `import "yaml";\nrequire("node:fs").writeFileSync(${JSON.stringify(join(fixture.root, "yaml-executed"))}, "bare-import");\n${readFileSync(corePath, "utf8")}`,
+        );
+      },
+    });
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain("tooling closure contains an unowned import");
+    expect(existsSync(sentinelPath)).toBe(false);
+  });
+
+  it("rejects ambiguous tooling aliases before execution", () => {
+    const { result, sentinelPath } = runYamlPackageSubprocess({
+      mutateTooling: (fixture) => {
+        writeFixture(
+          fixture.root,
+          "scripts/lib/release-version.mts",
+          `require("node:fs").writeFileSync(${JSON.stringify(join(fixture.root, "yaml-executed"))}, "ambiguous-alias");\n`,
+        );
+      },
+    });
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain("tooling import must resolve to one unambiguous file");
+    expect(existsSync(sentinelPath)).toBe(false);
+  });
+
+  it("rejects foreign yaml resolved from a distinct execution root", () => {
+    const fixture = createFixtureRepo();
+    writeFixture(
+      fixture.root,
+      "node_modules/yaml/package.json",
+      JSON.stringify({
+        name: "yaml",
+        version: "9.9.9",
+        type: "commonjs",
+        main: "./index.cjs",
+        exports: {
+          ".": "./index.cjs",
+          "./package.json": "./package.json",
+        },
+      }),
+    );
+    writeFixture(
+      fixture.root,
+      "node_modules/yaml/index.cjs",
+      `
+exports.parse = source => {
+  if (source.includes("rerun_group")) {
+    return { on: { workflow_dispatch: { inputs: { rerun_group: { options: ["package", "all", "ci"] } } } } };
+  }
+  if (source.includes("CORE_PACKAGE_DIRS")) {
+    return { jobs: { preflight: { steps: [{ env: { CORE_PACKAGE_DIRS: "packages/ai packages/gateway-protocol packages/gateway-client" } }] } } };
+  }
+  return {
+    jobs: {
+      publish_docker: { uses: "./.github/workflows/docker-release.yml" },
+      publish_vcr: { uses: "./.github/workflows/vercel-container-registry-publish.yml" }
+    }
+  };
+};
+`,
+    );
+    writeFixture(
+      fixture.root,
+      "foreign-yaml-harness.mts",
+      `
+import { produceReleasePlan } from "./scripts/release-plan-producer.mts";
+
+const toolingFullRef = ${JSON.stringify(fixture.toolingFullRef)};
+const toolingSha = ${JSON.stringify(fixture.toolingSha)};
+produceReleasePlan({
+  repoRoot: ${JSON.stringify(fixture.root)},
+  intent: "publish",
+  candidateSha: ${JSON.stringify(fixture.candidateSha)},
+  candidateRef: ${JSON.stringify(fixture.candidateRef)},
+  toolingSha,
+  toolingFullRef,
+  runGh: () => JSON.stringify({
+    ref: toolingFullRef,
+    object: { type: "commit", sha: toolingSha },
+  }),
+});
+`,
+    );
+    const result = spawnSync(process.execPath, [join(fixture.root, "foreign-yaml-harness.mts")], {
+      cwd: fixture.root,
+      encoding: "utf8",
+    });
+
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain("verified yaml retained tree digest mismatch");
+  });
+
+  it("accepts the complete installed yaml package tree", () => {
+    const { result, tempRoot } = runYamlPackageSubprocess();
+    expect(result.stderr).toBe("");
+    expect(result.status).toBe(0);
+    expect(yamlTempEntries(tempRoot)).toEqual([]);
+  });
+
+  it("rejects a changed yaml entry before executing it", () => {
+    const { result, sentinelPath } = runYamlPackageSubprocess({
+      mutate: ({ packageRoot, sentinelPath: sentinel }) => {
+        const entryPath = join(packageRoot, "dist/index.js");
+        writeFileSync(
+          entryPath,
+          `require("node:fs").writeFileSync(${JSON.stringify(sentinel)}, "executed");\n${readFileSync(entryPath, "utf8")}`,
+        );
+      },
+    });
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain("verified yaml retained tree digest mismatch");
+    expect(existsSync(sentinelPath)).toBe(false);
+  });
+
+  it("rejects a changed yaml transitive module before execution", () => {
+    const { result, sentinelPath } = runYamlPackageSubprocess({
+      mutate: ({ packageRoot, sentinelPath: sentinel }) => {
+        const transitivePath = join(packageRoot, "dist/public-api.js");
+        writeFileSync(
+          transitivePath,
+          `require("node:fs").writeFileSync(${JSON.stringify(sentinel)}, "executed");\n${readFileSync(transitivePath, "utf8")}`,
+        );
+      },
+    });
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain("verified yaml retained tree digest mismatch");
+    expect(existsSync(sentinelPath)).toBe(false);
+  });
+
+  it("rejects internal yaml package symlinks", () => {
+    const { result } = runYamlPackageSubprocess({
+      mutate: ({ packageRoot }) => {
+        const transitivePath = join(packageRoot, "dist/public-api.js");
+        unlinkSync(transitivePath);
+        symlinkSync("index.js", transitivePath);
+      },
+    });
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain("installed yaml package must not contain symbolic links");
+  });
+
+  it("rejects extra yaml package files", () => {
+    const { result } = runYamlPackageSubprocess({
+      mutate: ({ packageRoot }) => {
+        writeFileSync(join(packageRoot, "unexpected.js"), "module.exports = {};\n");
+      },
+    });
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain("verified yaml retained tree digest mismatch");
+  });
+
+  it("rejects missing yaml transitive files through tree attestation", () => {
+    const { result } = runYamlPackageSubprocess({
+      mutate: ({ packageRoot }) => {
+        rmSync(join(packageRoot, "dist/public-api.js"));
+      },
+    });
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain("verified yaml retained tree digest mismatch");
+    expect(result.stderr).not.toContain("MODULE_NOT_FOUND");
+  });
+
+  it("ignores poisoned direct yaml require cache entries", () => {
+    const { result, sentinelPath } = runYamlPackageSubprocess({
+      beforeProduce: ({ sentinelPath: sentinel }) => `
+const cacheModule = await import("node:module");
+const cacheFs = await import("node:fs");
+const cacheRequire = cacheModule.createRequire(import.meta.url);
+const ambientEntry = cacheRequire.resolve("yaml");
+cacheRequire(ambientEntry);
+cacheRequire.cache[ambientEntry].exports = {
+  parse() {
+    cacheFs.writeFileSync(${JSON.stringify(sentinel)}, "direct-cache");
+    return {};
+  }
+};
+`,
+    });
+    expect(result.status).toBe(0);
+    expect(existsSync(sentinelPath)).toBe(false);
+  });
+
+  it("ignores poisoned transitive yaml require cache entries", () => {
+    const { result, sentinelPath } = runYamlPackageSubprocess({
+      beforeProduce: ({ sentinelPath: sentinel }) => `
+const cacheModule = await import("node:module");
+const cacheFs = await import("node:fs");
+const cachePath = await import("node:path");
+const cacheRequire = cacheModule.createRequire(import.meta.url);
+const ambientEntry = cacheRequire.resolve("yaml");
+cacheRequire(ambientEntry);
+const publicApiPath = cachePath.join(cachePath.dirname(ambientEntry), "public-api.js");
+cacheRequire.cache[publicApiPath].exports = {
+  parse() {
+    cacheFs.writeFileSync(${JSON.stringify(sentinel)}, "transitive-cache");
+    return {};
+  },
+  parseAllDocuments() {},
+  parseDocument() {},
+  stringify() {}
+};
+delete cacheRequire.cache[ambientEntry];
+`,
+    });
+    expect(result.status).toBe(0);
+    expect(existsSync(sentinelPath)).toBe(false);
+  });
+
+  it("ignores parent yaml Module extension hooks", () => {
+    const { result, sentinelPath } = runYamlPackageSubprocess({
+      beforeProduce: ({ sentinelPath: sentinel }) => `
+const hookModule = (await import("node:module")).createRequire(import.meta.url)("node:module");
+const hookFs = await import("node:fs");
+const originalJsLoader = hookModule._extensions[".js"];
+hookModule._extensions[".js"] = function(module, filename) {
+  if (filename.includes("/yaml/") || filename.includes("openclaw-release-yaml-")) {
+    hookFs.writeFileSync(${JSON.stringify(sentinel)}, "extension-hook");
+  }
+  return originalJsLoader(module, filename);
+};
+`,
+    });
+    expect(result.status).toBe(0);
+    expect(existsSync(sentinelPath)).toBe(false);
+  });
+
+  it("does not inherit yaml NODE_OPTIONS or NODE_PATH loaders", () => {
+    const { result, sentinelPath } = runYamlPackageSubprocess({
+      mutate: ({ fixture, sentinelPath: sentinel }) => {
+        writeFixture(
+          fixture.root,
+          "yaml-preload.cjs",
+          `
+if (process.argv.some(value => value.includes("__openclaw_verified_yaml__"))) {
+  require("node:fs").writeFileSync(${JSON.stringify(sentinel)}, "node-options");
+}
+`,
+        );
+        writeFixture(
+          fixture.root,
+          "evil-node-path/yaml/index.js",
+          `require("node:fs").writeFileSync(${JSON.stringify(sentinel)}, "node-path");`,
+        );
+      },
+      environment: ({ fixture }) => ({
+        NODE_OPTIONS: `--require=${join(fixture.root, "yaml-preload.cjs")}`,
+        NODE_PATH: join(fixture.root, "evil-node-path"),
+      }),
+    });
+    expect(result.status).toBe(0);
+    expect(existsSync(sentinelPath)).toBe(false);
+  });
+
+  it("accepts exact-byte yaml hardlinks without creating a snapshot", () => {
+    const { result, tempRoot } = runYamlPackageSubprocess({
+      mutate: ({ fixture, packageRoot }) => {
+        const targetPath = join(packageRoot, "dist/public-api.js");
+        const linkSource = join(fixture.root, "public-api-hardlink-source.js");
+        writeFileSync(linkSource, readFileSync(targetPath));
+        unlinkSync(targetPath);
+        linkSync(linkSource, targetPath);
+        expect(statSync(targetPath).nlink).toBe(2);
+      },
+    });
+    expect(result.status).toBe(0);
+    expect(yamlTempEntries(tempRoot)).toEqual([]);
+  });
+
+  it("ignores a same-size ambient yaml replacement after byte retention", () => {
+    const mutationPath = "ambient-mutated";
+    const { result, sentinelPath, tempRoot } = runYamlPackageSubprocess({
+      beforeImport: ({ fixture, packageRoot, sentinelPath: sentinel }) => `
+const mutateModule = await import("node:module");
+const mutateFs = await import("node:fs");
+const mutateChildProcess = mutateModule.createRequire(import.meta.url)("node:child_process");
+const originalExecFileSync = mutateChildProcess.execFileSync;
+mutateChildProcess.execFileSync = function(command, args, options) {
+  if (command === process.execPath && args?.[0] === "--input-type=module") {
+    const entryPath = ${JSON.stringify(join(packageRoot, "dist/index.js"))};
+    const original = mutateFs.readFileSync(entryPath, "utf8");
+    const malicious =
+      'require("node:fs").writeFileSync(${JSON.stringify(sentinel)}, "ambient");' +
+      "module.exports={parse:JSON.parse};";
+    mutateFs.writeFileSync(entryPath, malicious.padEnd(original.length, " "));
+    mutateFs.writeFileSync(${JSON.stringify(join(fixture.root, mutationPath))}, "done");
+  }
+  return originalExecFileSync(command, args, options);
+};
+mutateModule.syncBuiltinESMExports();
+`,
+    });
+    expect(result.status).toBe(0);
+    expect(existsSync(join(result.status === 0 ? dirname(sentinelPath) : "", mutationPath))).toBe(
+      true,
+    );
+    expect(existsSync(sentinelPath)).toBe(false);
+    expect(yamlTempEntries(tempRoot)).toEqual([]);
+  });
+
+  it("fails malformed combined yaml parsing without creating a snapshot", () => {
+    const { result, tempRoot } = runYamlPackageSubprocess({
+      mutateTooling: (fixture) => {
+        writeFixture(fixture.root, ".github/workflows/full-release-validation.yml", "on: [\n");
+      },
+    });
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain("Flow sequence in block collection");
+    expect(yamlTempEntries(tempRoot)).toEqual([]);
+  });
+
+  it("rejects malformed publishable plugins while producing the plan", () => {
+    const fixture = createFixtureRepo("2026.8.1-beta.2", { malformedPlugin: true });
+    expect(() => produceReleasePlan(sourceParams(fixture))).toThrow(
+      /Publishable plugin metadata validation failed:[\s\S]*private must not be true[\s\S]*type must be "module"[\s\S]*README\.md must exist/u,
+    );
+  });
+
+  it("fails closed on malformed candidate manifests across both publishers and ReleasePlan", () => {
+    const fixture = createFixtureRepo("2026.8.1-beta.2", { malformedPluginJson: true });
+    const error = "plugin candidate manifest is malformed JSON: extensions/broken/package.json";
+    expect(() => collectPublishablePluginPackages(fixture.root)).toThrow(error);
+    expect(() => collectClawHubPublishablePluginPackages(fixture.root)).toThrow(error);
+    expect(() => produceReleasePlan(sourceParams(fixture))).toThrow(error);
+  });
+
+  it("rejects duplicate package names split across npm and ClawHub plugin sources", () => {
+    const fixture = createFixtureRepo("2026.8.1-beta.2", {
+      duplicateCrossTargetPackageName: true,
+    });
+
+    expect(() => produceReleasePlan(sourceParams(fixture))).toThrow(
+      "package @openclaw/duplicate is declared by multiple plugin sources",
+    );
+  });
+
+  it("rejects a plugin package name that collides with a core package source", () => {
+    const fixture = createFixtureRepo("2026.8.1-beta.2", {
+      corePackageNameCollision: true,
+    });
+
+    expect(() => produceReleasePlan(sourceParams(fixture))).toThrow(
+      "package inventory source mismatch for @openclaw/ai: extensions/shadow-ai/package.json and packages/ai/package.json",
+    );
+  });
+
+  it("rejects conflicting platform publication sources with the same id", () => {
+    const fixture = createFixtureRepo("2026.8.1-beta.2", {
+      conflictingPlatformId: true,
+    });
+
+    expect(() => produceReleasePlan(sourceParams(fixture))).toThrow(
+      "declares conflicting platform windows: .github/workflows/windows-node-release.yml and .github/workflows/docker-release.yml",
+    );
+  });
+
+  it("matches the exact current publisher inventory: 93 npm and 89 ClawHub packages", () => {
+    const root = tempDirs.make("openclaw-release-plan-current-");
+    const candidateSha = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: resolve("."),
+      encoding: "utf8",
+    }).trim();
+    execFileSync("git", ["clone", "-q", "--shared", "--no-checkout", resolve("."), root]);
+    execFileSync("git", ["checkout", "-q", "--detach", candidateSha], { cwd: root });
+    copyToolingClosure(root);
+    const toolingSha = commit(root, "tooling overlay", { allowEmpty: true });
+    execFileSync("git", ["update-ref", "refs/heads/main", toolingSha], { cwd: root });
+
+    const plan = produceReleasePlan({
+      repoRoot: root,
+      intent: "main-qualification",
+      validationIntent: "main-weekly",
+      candidateSha,
+      candidateRef: candidateSha,
+      toolingSha,
+      toolingFullRef: "refs/heads/main",
+      runGh: () => JSON.stringify({ status: "identical" }),
+    });
+    const npmPackages = plan.inventory.packages.filter((entry) => entry.targets.includes("npm"));
+    const clawHubPackages = plan.inventory.packages.filter((entry) =>
+      entry.targets.includes("clawhub"),
+    );
+    expect(npmPackages).toHaveLength(93);
+    expect(clawHubPackages).toHaveLength(89);
+    const coreNpmPackages = new Set([
+      "@openclaw/ai",
+      "@openclaw/gateway-client",
+      "@openclaw/gateway-protocol",
+      "openclaw",
+    ]);
+    expect(
+      npmPackages
+        .map((entry) => entry.name)
+        .filter((name) => !coreNpmPackages.has(name))
+        .toSorted(),
+    ).toEqual(
+      collectPublishablePluginPackages(root)
+        .map((plugin) => plugin.packageName)
+        .toSorted(),
+    );
+    expect(clawHubPackages.map((entry) => entry.name).toSorted()).toEqual(
+      collectClawHubPublishablePluginPackages(root)
+        .map((plugin) => plugin.packageName)
+        .toSorted(),
+    );
+    expect(npmPackages.map((entry) => entry.name)).toEqual(
+      expect.arrayContaining([
+        "@openclaw/ai",
+        "@openclaw/gateway-client",
+        "@openclaw/gateway-protocol",
+        "openclaw",
+      ]),
+    );
+  });
+
+  it("rejects recomputed locks with partial groups or bogus inventory", () => {
+    const fixture = createFixtureRepo();
+    const params = sourceParams(fixture);
+    const plan = produceReleasePlan(params);
+    const validLock = canonicalReleasePlanLockJson(createReleasePlanLock(plan));
+    expect(verifyReleasePlanLock(validLock, params).plan).toEqual(plan);
+
+    const partialGroups = structuredClone(plan);
+    partialGroups.validation.allowed_groups = ["all", "ci"];
+    const partialPlatforms = structuredClone(plan);
+    partialPlatforms.inventory.platforms = partialPlatforms.inventory.platforms.slice(0, -1);
+    const bogusPackages = structuredClone(plan);
+    bogusPackages.inventory.packages.push({
+      name: "zz-not-published",
+      targets: ["npm"],
+      version: plan.version,
+    });
+    for (const changed of [partialGroups, partialPlatforms, bogusPackages]) {
+      const redigested = canonicalReleasePlanLockJson(createReleasePlanLock(changed));
+      expect(() => verifyReleasePlanLock(redigested, params)).toThrow(
+        "repository-derived authority",
+      );
+    }
+  });
+});
diff --git a/test/scripts/release-validation-intent.test.ts b/test/scripts/release-validation-intent.test.ts
new file mode 100644
index 000000000000..3f2d3a03d087
--- /dev/null
+++ b/test/scripts/release-validation-intent.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import {
+  releaseValidationIntentForPurpose,
+  resolveReleaseValidationIntent,
+} from "../../scripts/release-validation-intent.mjs";
+
+describe("release validation intent", () => {
+  it.each([
+    ["release-beta", "beta", false, true],
+    ["release-stable", "stable", true, true],
+    ["main-daily", "beta", false, false],
+    ["main-weekly", "full", true, false],
+    ["diagnostic-full", "full", true, false],
+  ] as const)(
+    "defines %s as profile=%s soak=%s publishable=%s",
+    (intent, profile, soak, publishable) => {
+      expect(resolveReleaseValidationIntent(intent)).toEqual({
+        intent,
+        profile,
+        publishable,
+        soak,
+      });
+    },
+  );
+
+  it.each([
+    ["beta-publish", "release-beta"],
+    ["stable-publish", "release-stable"],
+    ["diagnostic", "diagnostic-full"],
+    ["postpublish-confidence", "diagnostic-full"],
+  ] as const)("maps %s to %s", (purpose, intent) => {
+    expect(releaseValidationIntentForPurpose(purpose)).toBe(intent);
+  });
+
+  it("requires main qualification callers to choose daily or weekly", () => {
+    expect(() => releaseValidationIntentForPurpose("main-qualification")).toThrow(
+      "requires an explicit validation intent",
+    );
+    expect(releaseValidationIntentForPurpose("main-qualification", "main-daily")).toBe(
+      "main-daily",
+    );
+    expect(releaseValidationIntentForPurpose("main-qualification", "main-weekly")).toBe(
+      "main-weekly",
+    );
+    expect(() =>
+      releaseValidationIntentForPurpose("main-qualification", "diagnostic-full"),
+    ).toThrow("does not allow validation intent");
+  });
+
+  it("treats legacy profile and soak inputs as assertions", () => {
+    expect(
+      resolveReleaseValidationIntent("main-daily", {
+        profile: "beta",
+        soak: false,
+      }),
+    ).toMatchObject({ intent: "main-daily" });
+    expect(() =>
+      resolveReleaseValidationIntent("main-daily", {
+        profile: "full",
+      }),
+    ).toThrow("profile assertion conflicts");
+    expect(() =>
+      resolveReleaseValidationIntent("main-daily", {
+        soak: true,
+      }),
+    ).toThrow("soak assertion conflicts");
+  });
+});

From 52371a9972c518a4ac4cfb9fd59f251ba42c1aca Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Fri, 21 Aug 2026 11:24:36 -0700
Subject: [PATCH 056/124] fix(ci): align lifecycle retry fixtures with terminal
 replies (#127295)

---
 ...registry.lifecycle-retry-grace.e2e.test.ts | 140 ++++++++++++++----
 1 file changed, 108 insertions(+), 32 deletions(-)

diff --git a/src/agents/subagents/registry/subagent-registry.lifecycle-retry-grace.e2e.test.ts b/src/agents/subagents/registry/subagent-registry.lifecycle-retry-grace.e2e.test.ts
index fe8d77e06266..b5a76c0bcbcb 100644
--- a/src/agents/subagents/registry/subagent-registry.lifecycle-retry-grace.e2e.test.ts
+++ b/src/agents/subagents/registry/subagent-registry.lifecycle-retry-grace.e2e.test.ts
@@ -236,7 +236,11 @@ describe("subagent registry lifecycle error grace", () => {
       const run = mod
         .listSubagentRunsForRequester(MAIN_REQUESTER_SESSION_KEY)
         .find((candidate) => candidate.runId === runId);
-      if (run?.cleanupHandled === false) {
+      if (
+        run?.cleanupHandled === false &&
+        run.delivery?.status === "pending" &&
+        run.delivery.payload
+      ) {
         return;
       }
       await vi.advanceTimersByTimeAsync(1);
@@ -282,12 +286,13 @@ describe("subagent registry lifecycle error grace", () => {
     throw new Error(`expected ${expectedCount} agent call(s), got ${getAgentCalls().length}`);
   };
 
-  const waitForFrozenResultText = async (runId: string, expectedText: string) => {
+  const waitForFrozenResult = async (runId: string, matches: (resultText: string) => boolean) => {
     for (let attempt = 0; attempt < 80; attempt += 1) {
       const run = mod
         .listSubagentRunsForRequester(MAIN_REQUESTER_SESSION_KEY)
         .find((candidate) => candidate.runId === runId);
-      if (run?.completion?.resultText === expectedText) {
+      const resultText = run?.completion?.resultText;
+      if (run && typeof resultText === "string" && matches(resultText)) {
         return run;
       }
       await vi.advanceTimersByTimeAsync(1);
@@ -296,11 +301,15 @@ describe("subagent registry lifecycle error grace", () => {
     throw new Error(`run ${runId} frozen result did not refresh`);
   };
 
+  const waitForFrozenResultText = async (runId: string, expectedText: string) =>
+    waitForFrozenResult(runId, (resultText) => resultText === expectedText);
+
   function registerCompletionRun(
     runId: string,
     childSuffix: string,
     task: string,
     requesterTurnRunId?: string,
+    expectsCompletionMessage = true,
   ) {
     mod.registerSubagentRun({
       runId,
@@ -311,7 +320,7 @@ describe("subagent registry lifecycle error grace", () => {
       requesterDisplayKey: MAIN_REQUESTER_DISPLAY_KEY,
       task,
       cleanup: "keep",
-      expectsCompletionMessage: true,
+      expectsCompletionMessage,
     });
   }
 
@@ -451,10 +460,18 @@ describe("subagent registry lifecycle error grace", () => {
       }),
     );
 
-    emitLifecycleEvent("run-yield-alpha", { phase: "end", endedAt: Date.now() });
+    emitLifecycleEvent("run-yield-alpha", {
+      phase: "end",
+      endedAt: Date.now(),
+      terminalReply: { disposition: "visible", text: "alpha complete" },
+    });
     await waitForAgentCallCount(1);
 
-    emitLifecycleEvent("run-yield-beta", { phase: "end", endedAt: Date.now() + 1 });
+    emitLifecycleEvent("run-yield-beta", {
+      phase: "end",
+      endedAt: Date.now() + 1,
+      terminalReply: { disposition: "visible", text: "beta complete" },
+    });
     await waitForAgentCallCount(2);
     const betaBeforeYield = mod
       .listSubagentRunsForRequester(MAIN_REQUESTER_SESSION_KEY)
@@ -583,7 +600,11 @@ describe("subagent registry lifecycle error grace", () => {
     expect(getRequesterWakeCalls()).toHaveLength(0);
     expect(liveChild.execution.status).toBe("running");
 
-    emitLifecycleEvent("run-frozen-live-child", { phase: "end", endedAt: Date.now() + 1 });
+    emitLifecycleEvent("run-frozen-live-child", {
+      phase: "end",
+      endedAt: Date.now() + 1,
+      terminalReply: { disposition: "visible", text: "live child complete" },
+    });
     await waitForAgentCallCount(1);
     await waitForDeliveredCleanup("run-frozen-live-child");
 
@@ -616,7 +637,11 @@ describe("subagent registry lifecycle error grace", () => {
     await vi.advanceTimersByTimeAsync(20_000);
     expect(getAgentCalls()).toHaveLength(0);
 
-    emitLifecycleEvent("run-transient-error", { phase: "end", endedAt: 1_250 });
+    emitLifecycleEvent("run-transient-error", {
+      phase: "end",
+      endedAt: 1_250,
+      terminalReply: { disposition: "visible", text: "Final answer transient" },
+    });
     await flushAsync();
 
     await waitForAgentCallCount(1);
@@ -650,7 +675,11 @@ describe("subagent registry lifecycle error grace", () => {
     agentCallPlan = ["throw", "ok"];
 
     const endedAt = Date.now();
-    emitLifecycleEvent("run-freeze", { phase: "end", endedAt });
+    emitLifecycleEvent("run-freeze", {
+      phase: "end",
+      endedAt,
+      terminalReply: { disposition: "visible", text: "Final answer X" },
+    });
     await flushAsync();
 
     await waitForAgentCallCount(1);
@@ -661,7 +690,11 @@ describe("subagent registry lifecycle error grace", () => {
     await waitForCleanupHandledFalse("run-freeze");
 
     setAssistantOutput("agent:main:subagent:freeze", "Late reply Y");
-    emitLifecycleEvent("run-freeze", { phase: "end", endedAt: endedAt + 100 });
+    emitLifecycleEvent("run-freeze", {
+      phase: "end",
+      endedAt: endedAt + 100,
+      terminalReply: { disposition: "visible", text: "Final answer X" },
+    });
     await flushAsync();
 
     await waitForAgentCallCount(2);
@@ -680,7 +713,14 @@ describe("subagent registry lifecycle error grace", () => {
     agentCallPlan = ["throw", "ok"];
 
     const endedAt = Date.now();
-    emitLifecycleEvent("run-refresh", { phase: "end", endedAt });
+    emitLifecycleEvent("run-refresh", {
+      phase: "end",
+      endedAt,
+      terminalReply: {
+        disposition: "visible",
+        text: "Both spawned. Waiting for completion events...",
+      },
+    });
     await flushAsync();
 
     await waitForAgentCallCount(1);
@@ -713,7 +753,14 @@ describe("subagent registry lifecycle error grace", () => {
     );
     expect((runAfterRefresh?.completion?.capturedAt ?? 0) >= firstCapturedAt).toBe(true);
 
-    emitLifecycleEvent("run-refresh", { phase: "end", endedAt: endedAt + 300 });
+    emitLifecycleEvent("run-refresh", {
+      phase: "end",
+      endedAt: endedAt + 300,
+      terminalReply: {
+        disposition: "visible",
+        text: "All 3 subagents complete. Here's the final summary.",
+      },
+    });
     await flushAsync();
 
     await waitForAgentCallCount(2);
@@ -729,7 +776,14 @@ describe("subagent registry lifecycle error grace", () => {
     agentCallPlan = ["throw", "ok"];
 
     const endedAt = Date.now();
-    emitLifecycleEvent("run-refresh-silent", { phase: "end", endedAt });
+    emitLifecycleEvent("run-refresh-silent", {
+      phase: "end",
+      endedAt,
+      terminalReply: {
+        disposition: "visible",
+        text: "All work complete, final summary",
+      },
+    });
     await flushAsync();
     await waitForCleanupHandledFalse("run-refresh-silent");
     await waitForFrozenResultText("run-refresh-silent", "All work complete, final summary");
@@ -747,7 +801,14 @@ describe("subagent registry lifecycle error grace", () => {
       .find((candidate) => candidate.runId === "run-refresh-silent");
     expect(runAfterSilent?.completion?.resultText).toBe("All work complete, final summary");
 
-    emitLifecycleEvent("run-refresh-silent", { phase: "end", endedAt: endedAt + 300 });
+    emitLifecycleEvent("run-refresh-silent", {
+      phase: "end",
+      endedAt: endedAt + 300,
+      terminalReply: {
+        disposition: "visible",
+        text: "All work complete, final summary",
+      },
+    });
     await flushAsync();
 
     await waitForAgentCallCount(2);
@@ -758,29 +819,24 @@ describe("subagent registry lifecycle error grace", () => {
   });
 
   it("regression, captures frozen completion output with 100KB cap and retains it for keep-mode cleanup", async () => {
-    registerCompletionRun("run-capped", "capped", "capped result test");
+    registerCompletionRun("run-capped", "capped", "capped result test", undefined, false);
     setAssistantOutput("agent:main:subagent:capped", "x".repeat(120 * 1024));
 
     emitLifecycleEvent("run-capped", { phase: "end", endedAt: Date.now() });
     await flushAsync();
 
-    await waitForAgentCallCount(1);
-    const cappedResults = getAgentResultsForChildSession("agent:main:subagent:capped");
-    expect(cappedResults).toHaveLength(1);
-    expect(cappedResults[0]).toContain("[truncated: frozen completion output exceeded 100KB");
-    expect(Buffer.byteLength(cappedResults[0] ?? "", "utf8")).toBeLessThanOrEqual(100 * 1024);
-
-    const run = mod
-      .listSubagentRunsForRequester(MAIN_REQUESTER_SESSION_KEY)
-      .find((candidate) => candidate.runId === "run-capped");
-    if (!run) {
-      throw new Error("expected capped run to exist");
-    }
+    const run = await waitForFrozenResult("run-capped", (resultText) =>
+      resultText.includes("[truncated: frozen completion output exceeded 100KB"),
+    );
+    expect(getAgentCalls()).toHaveLength(0);
     expect(run.runId).toBe("run-capped");
     expect(typeof run.completion?.resultText).toBe("string");
     expect(run.completion?.resultText).toContain(
       "[truncated: frozen completion output exceeded 100KB",
     );
+    expect(Buffer.byteLength(run.completion?.resultText ?? "", "utf8")).toBeLessThanOrEqual(
+      100 * 1024,
+    );
     expect(run.completion?.capturedAt).toBeTypeOf("number");
   });
 
@@ -823,7 +879,11 @@ describe("subagent registry lifecycle error grace", () => {
     expect(getAgentCalls()).toHaveLength(0);
 
     // Before the grace window, the run successfully ends (non-aborted)
-    emitLifecycleEvent("run-timeout-cancel", { phase: "end", endedAt: 4_500 });
+    emitLifecycleEvent("run-timeout-cancel", {
+      phase: "end",
+      endedAt: 4_500,
+      terminalReply: { disposition: "visible", text: "Final answer after recovery" },
+    });
     await flushAsync();
 
     await waitForAgentCallCount(1);
@@ -857,8 +917,16 @@ describe("subagent registry lifecycle error grace", () => {
     agentCallPlan = ["throw", "throw", "ok", "ok"];
 
     const parallelEndedAt = Date.now();
-    emitLifecycleEvent("run-parallel-a", { phase: "end", endedAt: parallelEndedAt });
-    emitLifecycleEvent("run-parallel-b", { phase: "end", endedAt: parallelEndedAt + 1 });
+    emitLifecycleEvent("run-parallel-a", {
+      phase: "end",
+      endedAt: parallelEndedAt,
+      terminalReply: { disposition: "visible", text: "Final answer A" },
+    });
+    emitLifecycleEvent("run-parallel-b", {
+      phase: "end",
+      endedAt: parallelEndedAt + 1,
+      terminalReply: { disposition: "visible", text: "Final answer B" },
+    });
     await flushAsync();
 
     await waitForAgentCallCount(2);
@@ -868,8 +936,16 @@ describe("subagent registry lifecycle error grace", () => {
     setAssistantOutput("agent:main:subagent:parallel-a", "Late overwrite");
     setAssistantOutput("agent:main:subagent:parallel-b", "Late overwrite");
 
-    emitLifecycleEvent("run-parallel-a", { phase: "end", endedAt: parallelEndedAt + 100 });
-    emitLifecycleEvent("run-parallel-b", { phase: "end", endedAt: parallelEndedAt + 101 });
+    emitLifecycleEvent("run-parallel-a", {
+      phase: "end",
+      endedAt: parallelEndedAt + 100,
+      terminalReply: { disposition: "visible", text: "Final answer A" },
+    });
+    emitLifecycleEvent("run-parallel-b", {
+      phase: "end",
+      endedAt: parallelEndedAt + 101,
+      terminalReply: { disposition: "visible", text: "Final answer B" },
+    });
     await flushAsync();
 
     await waitForAgentCallCount(4);

From ee79b0a49ae4b0ecd30f9e483c70c0f49f20232c Mon Sep 17 00:00:00 2001
From: xingzhou <zhang.guiping@xydigit.com>
Date: Sat, 22 Aug 2026 02:25:27 +0800
Subject: [PATCH 057/124] fix(channels): retry timed-out ingress messages
 (#127090)

Co-authored-by: PollyBot13 <pollybot13@gmail.com>
---
 extensions/telegram/AGENTS.md                 |   2 +-
 .../src/bot-handlers.inbound-processing.ts    |   7 ++
 ...bot-message-dispatch.pipeline-init.test.ts |  19 +++
 .../telegram/src/bot-message-dispatch.ts      |   6 +
 extensions/telegram/src/bot-message.test.ts   |  31 +++++
 extensions/telegram/src/bot-message.ts        |  12 ++
 extensions/telegram/src/bot.test.ts           |  59 +++++++++
 .../telegram/src/polling-session.test.ts      |  53 ++++----
 extensions/telegram/src/webhook.test.ts       |  13 +-
 extensions/zalouser/src/ingress.test.ts       |  15 ++-
 ...from-config.abort-and-dedupe.test-utils.ts | 113 ++++++++++++++++++
 .../reply/dispatch-from-config.gather.ts      |  20 +++-
 .../dispatch-from-config.prepare-context.ts   |   6 +-
 .../ingress-drain.debounce-failure.test.ts    |  15 ++-
 src/channels/message/ingress-drain.test.ts    |  12 +-
 src/channels/message/ingress-drain.ts         |  13 +-
 .../message/ingress-drain.watchdog.test.ts    |  51 +++++---
 17 files changed, 384 insertions(+), 63 deletions(-)

diff --git a/extensions/telegram/AGENTS.md b/extensions/telegram/AGENTS.md
index 70aa31f9bcb2..cdeeab04d540 100644
--- a/extensions/telegram/AGENTS.md
+++ b/extensions/telegram/AGENTS.md
@@ -17,7 +17,7 @@ Proof: `src/channels/message/ingress-drain.test.ts`,
 
 - Completed rows tombstone via `complete()`, never `delete`.
 - Complete at turn adoption, not settle. Deferred holds the claim; watchdog
-  stays armed through deferral; dead-letter reason `handler-timeout`.
+  stays armed through deferral; watchdog timeouts use the shared retry disposition.
 - One retry policy: attempt floor **and** age gate (defaults 8 / 24h).
 - Claim refresh heartbeat while dispatching/deferred (`claimLeaseMs / 3`).
 - Never silently complete on transient failure — release/fail via disposition.
diff --git a/extensions/telegram/src/bot-handlers.inbound-processing.ts b/extensions/telegram/src/bot-handlers.inbound-processing.ts
index 41b8e609d4ee..cb952eb581e1 100644
--- a/extensions/telegram/src/bot-handlers.inbound-processing.ts
+++ b/extensions/telegram/src/bot-handlers.inbound-processing.ts
@@ -246,6 +246,13 @@ export function createTelegramInboundProcessing({
         maxBytes: mediaMaxBytes,
         ...mediaRuntime,
       });
+      if (mediaRuntime.abortSignal?.aborted) {
+        const abortError =
+          mediaRuntime.abortSignal.reason ?? new Error("telegram media hydration owner aborted");
+        recordTelegramMessageProcessingResult({ kind: "failed-retryable", error: abortError });
+        releaseDispatchDedupeClaims(dispatchDedupeClaims, abortError);
+        return { kind: "ignored" };
+      }
       if (media) {
         await recordMessageResolvedMedia({ msg, media, botUserId: ctx.me?.id });
       }
diff --git a/extensions/telegram/src/bot-message-dispatch.pipeline-init.test.ts b/extensions/telegram/src/bot-message-dispatch.pipeline-init.test.ts
index 93385abc201d..c59925bbe34a 100644
--- a/extensions/telegram/src/bot-message-dispatch.pipeline-init.test.ts
+++ b/extensions/telegram/src/bot-message-dispatch.pipeline-init.test.ts
@@ -11,6 +11,25 @@ import type { TelegramMessageContext } from "./bot-message-dispatch.test-harness
 import { telegramInboundEventDelivery } from "./inbound-event-delivery.js";
 
 describeTelegramDispatch("dispatchTelegramMessage pipeline-init", () => {
+  it("does not enter the reply pipeline after the durable owner aborts", async () => {
+    const abortController = new AbortController();
+    abortController.abort(new Error("handler-timeout"));
+
+    await expect(
+      dispatchWithContext({
+        context: createContext(),
+        turnAdoptionLifecycle: {
+          abortSignal: abortController.signal,
+          onAdopted: vi.fn(),
+          onDeferred: vi.fn(),
+          onAbandoned: vi.fn(),
+        },
+      }),
+    ).resolves.toEqual({ kind: "completed" });
+
+    expect(createChannelMessageReplyPipeline).not.toHaveBeenCalled();
+  });
+
   it("keeps Telegram typing below its client expiry without a per-message cutoff", async () => {
     await dispatchWithContext({ context: createContext() });
 
diff --git a/extensions/telegram/src/bot-message-dispatch.ts b/extensions/telegram/src/bot-message-dispatch.ts
index 4095af2a5d46..19f0a843cfc4 100644
--- a/extensions/telegram/src/bot-message-dispatch.ts
+++ b/extensions/telegram/src/bot-message-dispatch.ts
@@ -384,6 +384,12 @@ export const dispatchTelegramMessage = async (
       }
     }
     loadFreshSessionEntry.clear();
+    // Media hydration and other pre-dispatch work can outlive the durable
+    // ingress watchdog. Never enter the reply pipeline after that owner has
+    // already fenced this attempt; the canonical spool row will retry it.
+    if (isDispatchSuperseded()) {
+      return { kind: "completed" };
+    }
     if (status.controller && !isRoomEvent) {
       void status.controller.setThinking();
     }
diff --git a/extensions/telegram/src/bot-message.test.ts b/extensions/telegram/src/bot-message.test.ts
index e9d9c21c1322..231ee04e9d8d 100644
--- a/extensions/telegram/src/bot-message.test.ts
+++ b/extensions/telegram/src/bot-message.test.ts
@@ -468,6 +468,37 @@ describe("telegram bot message processor", () => {
     expect(finalizeSpooledReplayResult).toHaveBeenCalledWith({ kind: "completed" }, "adopted");
   });
 
+  it("keeps a pre-adoption owner abort retryable when dispatch returns completed", async () => {
+    buildTelegramMessageContext.mockResolvedValue(createMessageContext());
+    const timeoutError = new Error("handler-timeout");
+    const abortController = new AbortController();
+    const finalizeSpooledReplayResult = vi.fn(
+      async (result: TelegramMessageProcessingResult): Promise<TelegramMessageProcessingResult> =>
+        result,
+    );
+    dispatchTelegramMessage.mockImplementationOnce(async () => {
+      abortController.abort(timeoutError);
+      return { kind: "completed" };
+    });
+    const processMessage = createTelegramMessageProcessor(baseDeps);
+
+    await expect(
+      processSampleMessage(
+        processMessage,
+        {
+          finalizeSpooledReplayResult,
+          spooledReplayAbortSignal: abortController.signal,
+        },
+        {},
+        { spooledReplay: true, isolateSpooledReplaySettlement: true },
+      ),
+    ).resolves.toEqual({ kind: "failed-retryable", error: timeoutError });
+    expect(finalizeSpooledReplayResult).toHaveBeenCalledWith(
+      { kind: "failed-retryable", error: timeoutError },
+      "terminal",
+    );
+  });
+
   it("retries durable replay protection after an active steer already committed", async () => {
     buildTelegramMessageContext.mockResolvedValue(createMessageContext());
     const finalizerError = new Error("dedupe commit failed");
diff --git a/extensions/telegram/src/bot-message.ts b/extensions/telegram/src/bot-message.ts
index 56b9ec1d6d58..62f4b7e321e7 100644
--- a/extensions/telegram/src/bot-message.ts
+++ b/extensions/telegram/src/bot-message.ts
@@ -447,6 +447,18 @@ export const createTelegramMessageProcessor = (deps: TelegramMessageProcessorDep
         if (settledResult) {
           return settledResult;
         }
+        if (turnAbortSignal.aborted) {
+          const abortResult: TelegramMessageProcessingResult =
+            turnAbortSignal.reason === "skipped"
+              ? { kind: "skipped" }
+              : {
+                  kind: "failed-retryable",
+                  error:
+                    turnAbortSignal.reason ??
+                    new Error("telegram spooled replay owner cancelled before adoption"),
+                };
+          return await settle(abortResult, "terminal");
+        }
         if (adoptionAttempted && !deferred && result.kind === "completed") {
           runtime.error?.(
             danger(
diff --git a/extensions/telegram/src/bot.test.ts b/extensions/telegram/src/bot.test.ts
index 64dc85f09d3e..3206d40551a6 100644
--- a/extensions/telegram/src/bot.test.ts
+++ b/extensions/telegram/src/bot.test.ts
@@ -4323,6 +4323,65 @@ describe("createTelegramBot", () => {
     expect(replySpy).not.toHaveBeenCalled();
   });
 
+  it("durably retries when primary media hydration outlives its claim owner", async () => {
+    const claimOwner = new AbortController();
+    const timeoutError = new Error("claim adoption stalled");
+    const mediaFetch = vi.fn(async (_input: string | URL | Request, init?: RequestInit) => {
+      claimOwner.abort(timeoutError);
+      expect(init?.signal?.aborted).toBe(true);
+      return new Response(new Uint8Array([0x89, 0x50, 0x4e, 0x47]), {
+        status: 200,
+        headers: { "content-type": "image/png" },
+      });
+    });
+    const ssrfMock = mockPinnedHostnameResolution();
+
+    try {
+      createTelegramBot({
+        token: "tok",
+        telegramTransport: makeTelegramTransport(mediaFetch as typeof fetch),
+      });
+      const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+      const update = {
+        update_id: 98083,
+        message: {
+          chat: { id: 7, type: "private" },
+          message_id: 9002,
+          caption: "inspect this image",
+          date: 1_736_380_800,
+          from: { id: 42, first_name: "Ada" },
+          photo: [{ file_id: "primary-photo-1" }],
+        },
+      };
+
+      const { result } = await runWithTelegramUpdateProcessingFrame(() =>
+        runWithTelegramSpooledReplayUpdate(
+          update,
+          () =>
+            handler({
+              update,
+              message: update.message,
+              me: { username: "openclaw_bot" },
+              getFile: async () => ({ file_path: "media/primary-photo.jpg" }),
+            }),
+          {
+            abortSignal: claimOwner.signal,
+            onAdopted: vi.fn(),
+            onDeferred: vi.fn(),
+            onAdoptionFinalizing: vi.fn(),
+            onAbandoned: vi.fn(),
+          },
+        ),
+      );
+
+      expect(result).toEqual({ kind: "failed-retryable", error: timeoutError });
+      expect(mediaFetch).toHaveBeenCalledTimes(1);
+      expect(replySpy).not.toHaveBeenCalled();
+    } finally {
+      ssrfMock.mockRestore();
+    }
+  });
+
   it("reuses resolved media when hydrating cached Telegram reply chains", async () => {
     const mediaFetch = vi.fn(
       async () =>
diff --git a/extensions/telegram/src/polling-session.test.ts b/extensions/telegram/src/polling-session.test.ts
index 3d4cf54a06e5..4786c6e16fc4 100644
--- a/extensions/telegram/src/polling-session.test.ts
+++ b/extensions/telegram/src/polling-session.test.ts
@@ -2711,7 +2711,7 @@ describe("TelegramPollingSession", () => {
     });
   });
 
-  it("fails buffered spooled claims instead of requeueing when deferred processing times out", async () => {
+  it("requeues buffered spooled claims when deferred processing times out", async () => {
     await withTempSpool(async (tempDir) => {
       const abort = new AbortController();
       const log = vi.fn();
@@ -2731,15 +2731,15 @@ describe("TelegramPollingSession", () => {
 
       await waitForTelegramTestState(() => expect(participants).toHaveLength(1));
       await waitForTelegramTestState(async () =>
-        expect(await failedUpdateIds(tempDir)).toEqual([42]),
+        expect(await pendingUpdateIds(tempDir, "all")).toEqual([42]),
       );
-      expect(await pendingUpdateIds(tempDir, "all")).toEqual([]);
+      expect(await failedUpdateIds(tempDir)).toEqual([]);
       expect(await listTelegramSpooledUpdateClaims({ spoolDir: tempDir })).toEqual([]);
       // Core drain watchdog log (display-id stripped of zero padding).
       expectLogIncludes(log, "claim→adoption stalled for event");
       expectLogIncludes(log, "handler-timeout");
-      expectLogExcludes(log, "spooled update 42 failed; keeping for retry");
-      expect(await failedUpdateReasons(tempDir)).toEqual([{ id: 42, reason: "handler-timeout" }]);
+      expectLogIncludes(log, "spooled update 42 failed; keeping for retry");
+      expect(await failedUpdateReasons(tempDir)).toEqual([]);
       abort.abort();
       stopWorker();
       await runPromise;
@@ -3512,9 +3512,8 @@ describe("TelegramPollingSession", () => {
     });
   });
 
-  it("recovers a lone active spooled handler owned by a replaced session (#84158)", async () => {
-    // Core drain: a lone hanging claim is dead-lettered by the adoption-stall
-    // watchdog so a replacement session is not blocked forever on that lane.
+  it("retries a lone active spooled handler in a replacement session (#84158)", async () => {
+    // Core drain releases a hanging claim so a replacement session retries it.
     vi.useFakeTimers({ shouldAdvanceTime: true });
     const firstAbort = new AbortController();
     const secondAbort = new AbortController();
@@ -3524,7 +3523,9 @@ describe("TelegramPollingSession", () => {
       releaseTurn = resolve;
     });
     const handleUpdate = vi.fn(async () => {
-      await turnDone;
+      if (handleUpdate.mock.calls.length === 1) {
+        await turnDone;
+      }
     });
     createTelegramBotMock.mockImplementation(() => makeIsolatedBot({ handleUpdate }));
     await writeSpooledTestUpdates(tempDir, [topicUpdate(42, 10, "lone active topic turn")]);
@@ -3558,10 +3559,10 @@ describe("TelegramPollingSession", () => {
       });
       const firstRunPromise = firstSession.runUntilAbort();
       await waitForTelegramTestState(() => expect(handleUpdate).toHaveBeenCalledTimes(1));
-      // Watchdog dead-letters the hanging claim before the session is replaced.
+      // Watchdog releases the hanging claim before the session is replaced.
       await vi.advanceTimersByTimeAsync(1_000);
       await waitForTelegramTestState(async () =>
-        expect(await failedUpdateIds(tempDir)).toEqual([42]),
+        expect(await pendingUpdateIds(tempDir, "all")).toEqual([42]),
       );
       firstAbort.abort();
       await vi.advanceTimersByTimeAsync(16_000);
@@ -3578,10 +3579,12 @@ describe("TelegramPollingSession", () => {
         },
       });
       const secondRunPromise = secondSession.runUntilAbort();
-      await vi.advanceTimersByTimeAsync(1_000);
-      // Tombstoned/failed claim is not re-dispatched; replacement is unblocked.
-      expect(handleUpdate).toHaveBeenCalledTimes(1);
-      expect(await pendingUpdateIds(tempDir, "all")).toEqual([]);
+      await vi.advanceTimersByTimeAsync(2_000);
+      await waitForTelegramTestState(() => expect(handleUpdate).toHaveBeenCalledTimes(2));
+      await waitForTelegramTestState(async () =>
+        expect(await pendingUpdateIds(tempDir, "all")).toEqual([]),
+      );
+      expect(await failedUpdateIds(tempDir)).toEqual([]);
 
       secondAbort.abort();
       await vi.advanceTimersByTimeAsync(20_000);
@@ -4434,10 +4437,8 @@ describe("TelegramPollingSession", () => {
     }
   });
 
-  it("fails a timed-out spooled handler and drains later same-lane updates without restart", async () => {
-    // Core drain: adoption-stall dead-letters 42 and frees the lane for 43 on
-    // the same bot. Session restart on handler timeout is removed private-drain
-    // behavior; the user-visible outcome is 42 failed and 43 processed.
+  it("retries a timed-out spooled handler before later same-lane updates without restart", async () => {
+    // Core drain releases 42 for retry before 43 on the same bot.
     vi.useFakeTimers({ shouldAdvanceTime: true });
     const abort = new AbortController();
     const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-telegram-spool-"));
@@ -4451,11 +4452,13 @@ describe("TelegramPollingSession", () => {
       init: vi.fn(async () => undefined),
       handleUpdate: vi.fn(async (update: { update_id?: number }) => {
         events.push(`bot:${update.update_id}`);
-        if (update.update_id === 42) {
+        if (update.update_id === 42 && events.filter((event) => event === "bot:42").length === 1) {
           // Hang until the core watchdog aborts the drain lifecycle.
           await new Promise<void>(() => {});
         }
-        abort.abort();
+        if (update.update_id === 43) {
+          abort.abort();
+        }
       }),
       stop: vi.fn(async () => undefined),
     };
@@ -4482,11 +4485,8 @@ describe("TelegramPollingSession", () => {
       const runPromise = session.runUntilAbort();
       await waitForTelegramTestState(() => expect(events).toEqual(["bot:42"]));
 
-      await vi.advanceTimersByTimeAsync(1_000);
-      await waitForTelegramTestState(async () =>
-        expect(await failedUpdateIds(tempDir)).toEqual([42]),
-      );
-      await waitForTelegramTestState(() => expect(events).toEqual(["bot:42", "bot:43"]));
+      await vi.advanceTimersByTimeAsync(2_000);
+      await waitForTelegramTestState(() => expect(events).toEqual(["bot:42", "bot:42", "bot:43"]));
       await vi.advanceTimersByTimeAsync(15_000);
       await runPromise;
 
@@ -4494,6 +4494,7 @@ describe("TelegramPollingSession", () => {
       expect(worker.createWorker).toHaveBeenCalledTimes(1);
       expect(createTelegramBotMock).toHaveBeenCalledTimes(1);
       expect(await pendingUpdateIds(tempDir, "all")).toEqual([]);
+      expect(await failedUpdateIds(tempDir)).toEqual([]);
       expectLogIncludes(log, "handler-timeout");
     } finally {
       abort.abort();
diff --git a/extensions/telegram/src/webhook.test.ts b/extensions/telegram/src/webhook.test.ts
index 78270977eb76..32cd7ceedee3 100644
--- a/extensions/telegram/src/webhook.test.ts
+++ b/extensions/telegram/src/webhook.test.ts
@@ -1350,10 +1350,11 @@ describe("startTelegramWebhook", () => {
     }
   });
 
-  it("keeps a timed-out webhook lane guarded until replay settles", async () => {
+  it("retries a timed-out webhook update before later same-lane updates", async () => {
     vi.useFakeTimers({ toFake: ["Date", "setTimeout", "clearTimeout"] });
     try {
       let finishFirstUpdate: (() => void) | undefined;
+      let finishRetry: (() => void) | undefined;
       const seenUpdateIds: number[] = [];
       const firstUpdate = telegramMessageUpdate(40, "slow");
       const secondUpdate = telegramMessageUpdate(41, "blocked");
@@ -1370,7 +1371,11 @@ describe("startTelegramWebhook", () => {
         seenUpdateIds.push(updateId);
         if (updateId === 40) {
           await new Promise<void>((resolve) => {
-            finishFirstUpdate = resolve;
+            if (seenUpdateIds.filter((id) => id === 40).length === 1) {
+              finishFirstUpdate = resolve;
+            } else {
+              finishRetry = resolve;
+            }
           });
         }
       });
@@ -1390,7 +1395,9 @@ describe("startTelegramWebhook", () => {
         expect(seenUpdateIds).toEqual([40]);
 
         finishFirstUpdate?.();
-        await waitForWebhookState(() => expect(seenUpdateIds).toEqual([40, 41]));
+        await waitForWebhookState(() => expect(seenUpdateIds).toEqual([40, 40]));
+        finishRetry?.();
+        await waitForWebhookState(() => expect(seenUpdateIds).toEqual([40, 40, 41]));
       } finally {
         await started.stop();
       }
diff --git a/extensions/zalouser/src/ingress.test.ts b/extensions/zalouser/src/ingress.test.ts
index 75af13cba2bd..d46a0aa97e4d 100644
--- a/extensions/zalouser/src/ingress.test.ts
+++ b/extensions/zalouser/src/ingress.test.ts
@@ -231,7 +231,7 @@ describe("Zalouser durable ingress", () => {
     });
   });
 
-  it("settles deferred bookkeeping when the adoption watchdog aborts a claim", async () => {
+  it("releases deferred bookkeeping for retry when the adoption watchdog aborts a claim", async () => {
     await withZalouserIngressTestQueue(async (queue) => {
       let deferredLifecycle: ZalouserIngressLifecycle | undefined;
       const dispatch = vi.fn(async (_message, lifecycle: ZalouserIngressLifecycle) => {
@@ -244,10 +244,21 @@ describe("Zalouser durable ingress", () => {
         runtime: runtime(),
         queue,
         dispatch,
+        pollIntervalMs: 60_000,
         adoptionStallTimeoutMs: 10,
       });
       await ingress.receive(createRawZalouserMessage({ msgId: "deferred-timeout" }));
-      await waitForZalouserIngressVerdict(queue, "deferred-timeout", "failed");
+      await vi.waitFor(async () => {
+        expect(await queue.listClaims()).toEqual([]);
+        expect(await queue.listFailed?.({ limit: "all" })).toEqual([]);
+        expect(await queue.listPending({ limit: "all" })).toMatchObject([
+          {
+            id: "deferred-timeout",
+            attempts: 1,
+            lastError: expect.stringContaining("handler-timeout"),
+          },
+        ]);
+      });
       expect(deferredLifecycle?.abortSignal.aborted).toBe(true);
 
       await ingress.stop();
diff --git a/src/auto-reply/reply/dispatch-from-config.abort-and-dedupe.test-utils.ts b/src/auto-reply/reply/dispatch-from-config.abort-and-dedupe.test-utils.ts
index 60f6bd1ef9c4..3d4e4c140667 100644
--- a/src/auto-reply/reply/dispatch-from-config.abort-and-dedupe.test-utils.ts
+++ b/src/auto-reply/reply/dispatch-from-config.abort-and-dedupe.test-utils.ts
@@ -1338,6 +1338,119 @@ describe("dispatchReplyFromConfig", () => {
     expect(replyResolver).toHaveBeenCalledTimes(1);
   });
 
+  it("releases inbound dedupe when durable ingress aborts before adoption", async () => {
+    setNoAbort();
+    hookMocks.runner.hasHooks.mockImplementation(
+      ((hookName?: string) => hookName === "before_dispatch") as () => boolean,
+    );
+    let markHookStarted!: () => void;
+    const hookStarted = new Promise<void>((resolve) => {
+      markHookStarted = resolve;
+    });
+    let releaseHook!: () => void;
+    const hookRelease = new Promise<void>((resolve) => {
+      releaseHook = resolve;
+    });
+    hookMocks.runner.runBeforeDispatch
+      .mockImplementationOnce(async () => {
+        markHookStarted();
+        await hookRelease;
+        return undefined;
+      })
+      .mockResolvedValue(undefined);
+
+    const ctx = buildTestCtx({
+      Provider: "telegram",
+      Surface: "telegram",
+      OriginatingChannel: "telegram",
+      OriginatingTo: "user:1",
+      SessionKey: "agent:main:telegram:direct:1",
+      MessageSid: "pre-adoption-retry",
+      BodyForAgent: "retry me",
+    });
+    const abortController = new AbortController();
+    const replyResolver = vi.fn(async () => ({ text: "retried" }) satisfies ReplyPayload);
+    const turnAdoptionLifecycle = {
+      onAdopted: vi.fn(async () => {}),
+      onDeferred: vi.fn(),
+      onSettled: vi.fn(),
+    };
+
+    const firstDispatch = dispatchReplyFromConfig({
+      ctx,
+      cfg: emptyConfig,
+      dispatcher: createDispatcher(),
+      replyOptions: {
+        abortSignal: abortController.signal,
+        turnAdoptionLifecycle,
+      },
+      replyResolver,
+    });
+    await hookStarted;
+    abortController.abort(new Error("handler-timeout"));
+    releaseHook();
+    await expect(firstDispatch).resolves.toMatchObject({ queuedFinal: false });
+    expect(replyResolver).not.toHaveBeenCalled();
+
+    await dispatchReplyFromConfig({
+      ctx,
+      cfg: emptyConfig,
+      dispatcher: createDispatcher(),
+      replyOptions: { turnAdoptionLifecycle },
+      replyResolver,
+    });
+    expect(replyResolver).toHaveBeenCalledOnce();
+  });
+
+  it("retains inbound dedupe when durable ingress aborts after adoption", async () => {
+    setNoAbort();
+    const ctx = buildTestCtx({
+      Provider: "telegram",
+      Surface: "telegram",
+      OriginatingChannel: "telegram",
+      OriginatingTo: "user:1",
+      SessionKey: "agent:main:telegram:direct:1",
+      MessageSid: "post-adoption-abort",
+      BodyForAgent: "run once",
+    });
+    const turnAdoptionLifecycle = {
+      onAdopted: vi.fn(async () => {}),
+      onDeferred: vi.fn(),
+      onSettled: vi.fn(),
+    };
+    const firstReplyResolver = vi.fn(
+      async (_ctx: MsgContext, opts?: GetReplyOptions): Promise<ReplyPayload | undefined> => {
+        await opts?.turnAdoptionLifecycle?.onAdopted();
+        const operation = (
+          opts as { replyOperation?: { abortForRestart: () => boolean } } | undefined
+        )?.replyOperation;
+        expect(operation?.abortForRestart()).toBe(true);
+        return await new Promise<never>(() => {});
+      },
+    );
+
+    await dispatchReplyFromConfig({
+      ctx,
+      cfg: emptyConfig,
+      dispatcher: createDispatcher(),
+      replyOptions: { turnAdoptionLifecycle },
+      replyResolver: firstReplyResolver,
+    });
+    expect(turnAdoptionLifecycle.onAdopted).toHaveBeenCalledOnce();
+
+    const duplicateReplyResolver = vi.fn(
+      async () => ({ text: "duplicate" }) satisfies ReplyPayload,
+    );
+    await dispatchReplyFromConfig({
+      ctx,
+      cfg: emptyConfig,
+      dispatcher: createDispatcher(),
+      replyOptions: { turnAdoptionLifecycle },
+      replyResolver: duplicateReplyResolver,
+    });
+    expect(duplicateReplyResolver).not.toHaveBeenCalled();
+  });
+
   it("keeps message-tool-only delivery mode on duplicate inbound returns", async () => {
     setNoAbort();
     const cfg = {
diff --git a/src/auto-reply/reply/dispatch-from-config.gather.ts b/src/auto-reply/reply/dispatch-from-config.gather.ts
index c977f43695c2..0ccf468ce298 100644
--- a/src/auto-reply/reply/dispatch-from-config.gather.ts
+++ b/src/auto-reply/reply/dispatch-from-config.gather.ts
@@ -64,15 +64,33 @@ export async function gatherDispatchRequest(
   const ctx = isFinalizedInboundContext(params.ctx)
     ? params.ctx
     : finalizeInboundContext(params.ctx);
+  const turnAdoptionLifecycle = params.replyOptions?.turnAdoptionLifecycle;
+  const turnAdoptionState = { adopted: false };
   const normalizedParams: DispatchFromConfigParams = {
     ...params,
     ctx,
-    replyOptions: { ...params.replyOptions },
+    replyOptions: {
+      ...params.replyOptions,
+      ...(turnAdoptionLifecycle
+        ? {
+            turnAdoptionLifecycle: {
+              ...turnAdoptionLifecycle,
+              onAdopted: async () => {
+                // The upstream owner is durable only after its callback commits.
+                // A rejected callback must leave replay dedupe releasable.
+                await turnAdoptionLifecycle.onAdopted();
+                turnAdoptionState.adopted = true;
+              },
+            },
+          }
+        : {}),
+    },
   };
   const state = {
     params: normalizedParams,
     messageAuditTerminal,
     inboundDedupeReplayUnsafe: false,
+    turnAdoptionState: turnAdoptionLifecycle ? turnAdoptionState : undefined,
   };
   const { cfg, dispatcher } = normalizedParams;
   const replyOperationRunState: ReplyOperationRunState =
diff --git a/src/auto-reply/reply/dispatch-from-config.prepare-context.ts b/src/auto-reply/reply/dispatch-from-config.prepare-context.ts
index 7063cbc7032a..8f6f75103efa 100644
--- a/src/auto-reply/reply/dispatch-from-config.prepare-context.ts
+++ b/src/auto-reply/reply/dispatch-from-config.prepare-context.ts
@@ -474,7 +474,11 @@ export async function prepareDispatchOperationContext(state: PrepareDispatchDeli
           isError: true,
         })
       : false;
-    commitInboundDedupeIfClaimed();
+    if (state.turnAdoptionState && !state.turnAdoptionState.adopted) {
+      releaseInboundDedupeIfClaimed();
+    } else {
+      commitInboundDedupeIfClaimed();
+    }
     recordProcessed("completed", { reason: "reply_operation_aborted" });
     markIdle("message_completed");
     state.completeDispatchReplyOperation();
diff --git a/src/channels/message/ingress-drain.debounce-failure.test.ts b/src/channels/message/ingress-drain.debounce-failure.test.ts
index 8a8396f31eba..7de117f18fc4 100644
--- a/src/channels/message/ingress-drain.debounce-failure.test.ts
+++ b/src/channels/message/ingress-drain.debounce-failure.test.ts
@@ -85,7 +85,7 @@ describe("channel ingress drain debounce failures", () => {
     });
   });
 
-  it("keeps watchdog recovery after retry settlement fails", async () => {
+  it("keeps watchdog ownership when retry settlement keeps failing", async () => {
     vi.useFakeTimers();
     await withTempState(async (stateDir) => {
       let clock = 10_000;
@@ -98,6 +98,7 @@ describe("channel ingress drain debounce failures", () => {
       queue.release = async () => {
         throw new Error("persistent release failure");
       };
+      const log = vi.fn();
 
       const sessionError = new Error("Session changed while starting work. Retry.");
       const debouncer = createInboundDebouncer<{ lifecycle: ChannelIngressDispatchLifecycle }>({
@@ -116,6 +117,7 @@ describe("channel ingress drain debounce failures", () => {
         queue,
         now: () => clock,
         adoptionStallTimeoutMs: 200_000,
+        onLog: log,
         dispatchClaimedEvent: async (_event, lifecycle) => {
           await debouncer.enqueue({ lifecycle });
           return { kind: "deferred" };
@@ -134,11 +136,14 @@ describe("channel ingress drain debounce failures", () => {
 
       clock += 73_000;
       await vi.advanceTimersByTimeAsync(73_000);
-      expect(await queue.listClaims()).toEqual([]);
-      expect(await queue.listFailed?.({ limit: "all" })).toMatchObject([
-        { id: "debounced-settlement-failure", reason: "handler-timeout" },
+      expect((await queue.listClaims()).map((claim) => claim.id)).toEqual([
+        "debounced-settlement-failure",
       ]);
-      expect(drain.activeLaneKeys().has("shared")).toBe(false);
+      expect(await queue.listFailed?.({ limit: "all" })).toEqual([]);
+      expect(drain.activeLaneKeys().has("shared")).toBe(true);
+      expect(log).toHaveBeenCalledWith(
+        expect.stringContaining("applying retry policy (handler-timeout)"),
+      );
       drain.dispose();
     });
   });
diff --git a/src/channels/message/ingress-drain.test.ts b/src/channels/message/ingress-drain.test.ts
index 4baa332b51de..09726239863b 100644
--- a/src/channels/message/ingress-drain.test.ts
+++ b/src/channels/message/ingress-drain.test.ts
@@ -300,9 +300,15 @@ describe("channel ingress drain", () => {
 
       clock += 1_000;
       await vi.advanceTimersByTimeAsync(1_000);
-      await vi.waitFor(async () => expect(await queue.listFailed?.()).toHaveLength(1));
-      const failed = await queue.listFailed?.();
-      expect(failed?.[0]).toMatchObject({ id: "released-stall", reason: "handler-timeout" });
+      await vi.waitFor(async () => expect(await queue.listClaims()).toEqual([]));
+      expect(await queue.listFailed?.()).toEqual([]);
+      expect(await queue.listPending({ limit: "all" })).toMatchObject([
+        {
+          id: "released-stall",
+          attempts: 1,
+          lastError: expect.stringContaining("handler-timeout"),
+        },
+      ]);
       drain.dispose();
     });
   });
diff --git a/src/channels/message/ingress-drain.ts b/src/channels/message/ingress-drain.ts
index 79313ba84409..e91f30e5fbbb 100644
--- a/src/channels/message/ingress-drain.ts
+++ b/src/channels/message/ingress-drain.ts
@@ -47,7 +47,7 @@ import {
 export { bindIngressLifecycleToReplyOptions } from "./ingress-drain-lifecycle.js";
 export { isIngressAdoptionLostError } from "./ingress-drain-state.js";
 
-/** Default claim→adoption stall before dead-lettering with handler-timeout. */
+/** Default claim→adoption stall before applying the shared retry disposition. */
 export const DEFAULT_INGRESS_ADOPTION_STALL_MS = 5 * 60 * 1000;
 
 /** Bounded tombstone write retries — wedged ownership beats silent double-dispatch. */
@@ -397,25 +397,26 @@ export function createChannelIngressDrain<
       }
       const ageMs = now() - state.startedAt;
       const displayId = state.eventId.replace(/^0+(?=\d)/, "") || state.eventId;
-      const message = `Channel ingress claim→adoption stalled for event ${displayId} on lane ${state.laneKey} after ${ageMs}ms; marking failed (handler-timeout).`;
+      const message = `Channel ingress claim→adoption stalled for event ${displayId} on lane ${state.laneKey} after ${ageMs}ms; applying retry policy (handler-timeout).`;
+      const timeoutError = new Error(message);
       // Closed guillotine flag — catch must not string-sniff errors.
       state.guillotined = true;
       clearStallTimer(state);
       log(message);
       try {
-        state.abortController.abort(new Error(message));
+        state.abortController.abort(timeoutError);
       } catch {
         // AbortController.abort is not fallible in practice.
       }
-      // Same bounded-retry/hold-ownership policy as tombstone: a fail write
+      // Route the timeout through the canonical retry owner. A release/fail write
       // error must not falsely settle (would stop heartbeat and wedge recovery).
       void state
         .settleOnce(async () => {
-          await failClaim(state.claim, "handler-timeout", message);
+          await applyFailureDisposition(state.claim, timeoutError);
         })
         .catch((err: unknown) => {
           log(
-            `ingress drain: failed to dead-letter stalled event ${displayId}; holding claim: ${formatError(err)}`,
+            `ingress drain: failed to settle stalled event ${displayId}; holding claim: ${formatError(err)}`,
           );
         });
     }, adoptionStallTimeoutMs);
diff --git a/src/channels/message/ingress-drain.watchdog.test.ts b/src/channels/message/ingress-drain.watchdog.test.ts
index 49f5788ab7da..62e375396b34 100644
--- a/src/channels/message/ingress-drain.watchdog.test.ts
+++ b/src/channels/message/ingress-drain.watchdog.test.ts
@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { closeOpenClawStateDatabaseForTest } from "../../state/openclaw-state-db.js";
-import { createChannelIngressDrain } from "./ingress-drain.js";
+import type { ChannelIngressDispatchLifecycle } from "./ingress-drain-lifecycle.js";
+import { createChannelIngressDrain, isIngressAdoptionLostError } from "./ingress-drain.js";
 import {
   createTestIngressQueue,
   type IngressDrainTestPayload as Payload,
@@ -17,19 +18,27 @@ describe("channel ingress drain watchdog", () => {
     closeOpenClawStateDatabaseForTest();
   });
 
-  it("guillotines pre-adoption stalls with handler-timeout", async () => {
+  it("retries pre-adoption stalls in lane order and fences late adoption", async () => {
     await withTempState(async (stateDir) => {
       let clock = 10_000;
       const queue = createTestIngressQueue(stateDir, { now: () => clock });
       await queue.enqueue("evt-stall", { text: "x" }, { laneKey: "l1" });
+      await queue.enqueue("evt-next", { text: "next" }, { laneKey: "l1", receivedAt: clock + 1 });
+      const dispatched: string[] = [];
+      let stalledLifecycle: ChannelIngressDispatchLifecycle | undefined;
 
       const drain = createChannelIngressDrain<Payload>({
         queue,
         now: () => clock,
         adoptionStallTimeoutMs: 5_000,
-        dispatchClaimedEvent: async () => {
-          // Never adopt, never return -- stall until watchdog.
-          await new Promise(() => {});
+        retryPolicy: { baseMs: 1_000, maxMs: 1_000 },
+        dispatchClaimedEvent: async (event, lifecycle) => {
+          dispatched.push(event.id);
+          if (!stalledLifecycle) {
+            stalledLifecycle = lifecycle;
+            await new Promise(() => {});
+          }
+          await lifecycle.onAdopted();
         },
       });
 
@@ -38,11 +47,20 @@ describe("channel ingress drain watchdog", () => {
       await vi.advanceTimersByTimeAsync(5_000);
       await drain.waitForIdle();
 
-      const reenqueue = await queue.enqueue("evt-stall", { text: "x" });
-      expect(reenqueue.kind).toBe("failed");
-      if (reenqueue.kind === "failed") {
-        expect(reenqueue.record.reason).toBe("handler-timeout");
-      }
+      expect(await queue.listFailed?.({ limit: "all" })).toEqual([]);
+      expect(await queue.listPending({ limit: "all", orderBy: "received" })).toMatchObject([
+        { id: "evt-stall", attempts: 1, lastError: expect.stringContaining("handler-timeout") },
+        { id: "evt-next", attempts: 0 },
+      ]);
+      await expect(stalledLifecycle?.onAdopted()).rejects.toSatisfy(isIngressAdoptionLostError);
+
+      expect(await drain.drainOnce()).toEqual({ started: 0 });
+      clock += 1_000;
+      expect(await drain.drainOnce()).toEqual({ started: 1 });
+      await drain.waitForIdle();
+      expect(await drain.drainOnce()).toEqual({ started: 1 });
+      await drain.waitForIdle();
+      expect(dispatched).toEqual(["evt-stall", "evt-stall", "evt-next"]);
       drain.dispose();
     });
   });
@@ -70,11 +88,14 @@ describe("channel ingress drain watchdog", () => {
       await vi.advanceTimersByTimeAsync(5_000);
       await drain.waitForIdle();
 
-      const reenqueue = await queue.enqueue("evt-def-stall", { text: "x" });
-      expect(reenqueue.kind).toBe("failed");
-      if (reenqueue.kind === "failed") {
-        expect(reenqueue.record.reason).toBe("handler-timeout");
-      }
+      expect(await queue.listFailed?.({ limit: "all" })).toEqual([]);
+      expect(await queue.listPending({ limit: "all" })).toMatchObject([
+        {
+          id: "evt-def-stall",
+          attempts: 1,
+          lastError: expect.stringContaining("handler-timeout"),
+        },
+      ]);
       drain.dispose();
     });
   });

From ccbfa6c3a3251dad79d7f93e612c914defb7d1ac Mon Sep 17 00:00:00 2001
From: Josh Avant <830519+joshavant@users.noreply.github.com>
Date: Fri, 21 Aug 2026 11:33:32 -0700
Subject: [PATCH 058/124] feat(ui): explain decision receipts in Activity
 (#126007)

* fix(audit): project safe decision receipt displays

* docs(agents): preserve audit display privacy

* fix(ci): satisfy audit receipt guardrails
---
 AGENTS.md                                     |   1 +
 .../OpenClawProtocol/GatewayModels.swift      |  54 +-
 docs/cli/audit.md                             |  33 +-
 docs/gateway/audit.md                         |  19 +-
 docs/web/control-ui.md                        |  10 +-
 .../gateway-protocol/src/public-schema.ts     |   1 +
 .../src/schema/audit-run.test.ts              |  54 +-
 .../gateway-protocol/src/schema/audit-run.ts  |  44 +-
 .../protocol-schema-fragment-operations.ts    |   1 +
 src/audit/execution-decision-facts.test.ts    | 304 ++++++---
 src/audit/execution-decision-facts.ts         | 106 ++--
 src/audit/execution-decision-receipts.ts      | 113 +++-
 src/audit/execution-identity-context.ts       | 233 +++----
 src/audit/message-delivery-audit-store.ts     |   4 +-
 .../message-delivery-progress-store.test.ts   |  26 +-
 src/audit/message-delivery-receipts.ts        |  10 +-
 src/commands/audit.test.ts                    |  96 +--
 src/commands/audit.ts                         |  43 +-
 .../operator-approval-receipts.test.ts        | 160 ++++-
 src/gateway/operator-approval-store.ts        | 367 ++++++-----
 src/gateway/server-methods/audit.test.ts      | 150 +++++
 src/gateway/server-methods/audit.ts           |  45 +-
 .../runtime/agent-run-decision-receipt.ts     |  34 +-
 .../runtime/agent-run-identity-inspection.ts  |   7 +-
 .../codex-native-approval-receipt.e2e.test.ts |  18 +-
 ui/src/e2e/activity-run-inspector.e2e.test.ts | 586 +++++++++++++++---
 .../activity-run-inspector.test-fixtures.ts   | 136 ++++
 ui/src/i18n/locales/en-activity.ts            |  40 +-
 ui/src/pages/activity/activity-page.test.ts   | 102 +++
 ui/src/pages/activity/activity-page.ts        | 153 ++++-
 ui/src/pages/activity/route.test.ts           |  30 +-
 .../activity/run-inspector-evidence-view.ts   | 331 ++++++++++
 .../activity/run-inspector-model.test.ts      |  71 ++-
 ui/src/pages/activity/run-inspector-model.ts  |  90 ++-
 .../pages/activity/run-inspector-view.test.ts |  71 ++-
 ui/src/pages/activity/run-inspector-view.ts   | 181 +++---
 ui/src/pages/activity/run-inspector.css       |  80 ++-
 37 files changed, 2972 insertions(+), 832 deletions(-)
 create mode 100644 ui/src/e2e/activity-run-inspector.test-fixtures.ts
 create mode 100644 ui/src/pages/activity/run-inspector-evidence-view.ts

diff --git a/AGENTS.md b/AGENTS.md
index 6c08ec46bd94..474bf5355f84 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -154,6 +154,7 @@ Review invariants; full doctrine: `docs/gateway/audit.md`.
 - Invoker evidence is tri-state: tagged principal-bearing input is `present`, tagged principal-less input is `unknown`, and omission alone is `absent`. Validate the closed raw variant before projection or field dropping; reject malformed, mixed, untagged, or extra-field input instead of normalizing it to `unknown` or absence.
 - Each outer admitted turn owns one immutable `executionId` and `contextId`; `runId` is non-unique correlation. Retries, fallbacks, and recovery reuse the original admission identity. Only byte-identical canonical replay is idempotent.
 - Decision receipts adapt owner-native durable decisions; `execution_decision_facts` is only for boundaries without an owner-native record, never duplicates approvals, and stays dormant until an explicit product-boundary producer with an operator retention opt-in exists — the 30-day retention bound does not authorize default collection. Receipt coverage `enforced` is diagnostic, not authority: emit it only when the owner changed the outcome and the exact context/execution/run tuple validates; otherwise `unknown`.
+- `audit.run.inspect` exposes only the Gateway-owned `decisionDisplays` allowlist; display trust comes from owner-held call-path provenance, never receipt-controlled `source.owner` or prose. Pair every selected owner row or event with a required opaque selector from the same query or page result; never derive or requery selectors from private receipt, resolution, or event identifiers, or drop corrupt, oversized, or unlinked outcomes.
 - Admission may only validate, bound, freeze, and enqueue through the shared audit writer. Admission validates only a recursively owned, enumerable, accessor-free data snapshot constructed from descriptors before schema checks or ordinary property reads; inherited properties are absent and accessors never run. No synchronous SQLite, schema, filesystem, HMAC-key, or readiness work. Audit failure never delays or aborts execution.
 - Raw identity references are transient worker-message data. Never persist, export, inspect, or log them. Public Plugin SDK ingress must strip private recovery/admission authority, including JavaScript extra and inherited properties.
 - Channel participant evidence is host-minted only from an exact active registered native-plugin resolver result and redeemed once against the finalized context plus plugin record/lifecycle epoch. Missing, copied, substituted, replayed, stale, scope-changed, or mixed evidence becomes `unknown`. Mixed participants may remove sender-derived authority only; never widen or erase independent tools, grants, routing, or approval authority.
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
index 27d8b024f549..2ff70bde0e5f 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
@@ -11027,6 +11027,52 @@ public struct DecisionReceiptV1: Codable, Sendable {
     }
 }
 
+public struct DecisionReceiptDisplayV1: Codable, Sendable {
+    public let schemaversion: Double
+    public let selectorid: String
+    public let occurredat: Int
+    public let action: [String: AnyCodable]
+    public let decision: [String: AnyCodable]
+    public let enforcement: [String: AnyCodable]
+    public let provenance: AnyCodable
+    public let missingevidence: [String]
+    public let remediation: [[String: AnyCodable]]
+
+    public init(
+        schemaversion: Double,
+        selectorid: String,
+        occurredat: Int,
+        action: [String: AnyCodable],
+        decision: [String: AnyCodable],
+        enforcement: [String: AnyCodable],
+        provenance: AnyCodable,
+        missingevidence: [String],
+        remediation: [[String: AnyCodable]])
+    {
+        self.schemaversion = schemaversion
+        self.selectorid = selectorid
+        self.occurredat = occurredat
+        self.action = action
+        self.decision = decision
+        self.enforcement = enforcement
+        self.provenance = provenance
+        self.missingevidence = missingevidence
+        self.remediation = remediation
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case schemaversion = "schemaVersion"
+        case selectorid = "selectorId"
+        case occurredat = "occurredAt"
+        case action
+        case decision
+        case enforcement
+        case provenance
+        case missingevidence = "missingEvidence"
+        case remediation
+    }
+}
+
 public struct AuditRunIdentityPresentV1: Codable, Sendable {
     public let state: String
     public let context: ExecutionIdentityContextV1
@@ -11165,7 +11211,7 @@ public struct AuditRunInspectResult: Codable, Sendable {
     public let schemaversion: Double
     public let run: [String: AnyCodable]
     public let identity: AuditRunIdentityV1
-    public let decisions: [DecisionReceiptV1]
+    public let decisiondisplays: [DecisionReceiptDisplayV1]
     public let coverage: [String: AnyCodable]
     public let nextdecisioncursor: String?
     public let nextexecutioncursor: String?
@@ -11174,7 +11220,7 @@ public struct AuditRunInspectResult: Codable, Sendable {
         schemaversion: Double,
         run: [String: AnyCodable],
         identity: AuditRunIdentityV1,
-        decisions: [DecisionReceiptV1],
+        decisiondisplays: [DecisionReceiptDisplayV1],
         coverage: [String: AnyCodable],
         nextdecisioncursor: String? = nil,
         nextexecutioncursor: String? = nil)
@@ -11182,7 +11228,7 @@ public struct AuditRunInspectResult: Codable, Sendable {
         self.schemaversion = schemaversion
         self.run = run
         self.identity = identity
-        self.decisions = decisions
+        self.decisiondisplays = decisiondisplays
         self.coverage = coverage
         self.nextdecisioncursor = nextdecisioncursor
         self.nextexecutioncursor = nextexecutioncursor
@@ -11192,7 +11238,7 @@ public struct AuditRunInspectResult: Codable, Sendable {
         case schemaversion = "schemaVersion"
         case run
         case identity
-        case decisions
+        case decisiondisplays = "decisionDisplays"
         case coverage
         case nextdecisioncursor = "nextDecisionCursor"
         case nextexecutioncursor = "nextExecutionCursor"
diff --git a/docs/cli/audit.md b/docs/cli/audit.md
index 398333a9b7ab..76029cd7799e 100644
--- a/docs/cli/audit.md
+++ b/docs/cli/audit.md
@@ -152,14 +152,15 @@ valid host-bound evidence; it never means allowed. `unsupported` is reserved
 for a named path with no authoritative Phase 0 integration. A plugin-provided
 sender or structurally copied resolver result cannot upgrade either state.
 
-A terminal approval receipt shows `allowed` or `denied`, its stable reason
-code, enforcement state, authoritative source boundary, policy and grant
-references, context fields used, and remediation. Expired and cancelled
+A terminal approval display shows `allowed` or `denied`, its stable reason
+code, enforcement state, verified producer class, policy and grant counts,
+context fields used, and remediation. Expired and cancelled
 approvals are denied non-actions with distinct reason codes. `no-route` is an
 enforced denial only when the approval owner recorded that terminal state. A
-corrupt approval is `unknown`. The text view labels `operator_approvals` as an
-authoritative owner-native SQLite record retained for 30 days; JSON preserves
-the same source owner and record reference without lossy reformatting.
+corrupt approval is `unknown`. The text view labels a verified
+operator-approval producer as an authoritative owner-native SQLite record
+retained for 30 days. Neither text nor JSON exposes the raw source owner, record
+reference, policy reference, or grant reference.
 `enforced` requires the approval's immutable owner-local binding to match the
 selected context, execution, and run exactly. A missing, malformed, or
 mismatched binding reports `operator_approval_execution_link_missing`,
@@ -192,8 +193,9 @@ their exact tuple was recorded and the gate changed the outcome.
 Portable actions and early suppressions that have no durable delivery record
 use the generic decision-fact owner instead of duplicating delivery state.
 
-JSON output is the Gateway result without lossy reformatting. An exact result contains one
-bounded V1 context (maximum 16 KiB), up to 100 decision receipts, coverage and
+JSON output is the Gateway's safe-only result without lossy reformatting. An
+exact result contains one bounded V1 context (maximum 16 KiB), up to 100
+`decisionDisplays`, coverage and
 missing-evidence codes, and an optional `nextDecisionCursor`. An ambiguous run
 result instead contains at most 50 execution candidates and an optional
 `nextExecutionCursor`. Sensitive domain,
@@ -303,18 +305,25 @@ openclaw gateway call audit.run.inspect \
   --params '{"executionId":"5da4c4c3-e1c9-4c95-a17d-6e5c10fd45cf","decisionLimit":50}'
 ```
 
-Its result is `{ "schemaVersion": 1, "run": ..., "identity": ..., "decisions":
-..., "coverage": ..., "nextDecisionCursor"?: ..., "nextExecutionCursor"?: ... }`.
+Its result is `{ "schemaVersion": 1, "run": ..., "identity": ...,
+"decisionDisplays": ..., "coverage": ..., "nextDecisionCursor"?: ...,
+"nextExecutionCursor"?: ... }`. The required `decisionDisplays` array is the
+only receipt presentation field. Raw owner receipts and a `decisions` key never
+cross the Gateway boundary.
 The closed request accepts exactly one of `executionId` or `runId`.
 `decisionLimit` is 1–100 and `decisionCursor` is optional. Run discovery also
 accepts `executionLimit` from 1–50 and an optional `executionCursor`. A run
 with multiple retained executions returns the typed `ambiguous` identity state
-and no identity context or decisions until the caller selects an execution id.
+and no identity context; its required `decisionDisplays` array is empty until
+the caller selects an execution id.
 For one selected context, receipt paging starts with admission, then reads
 owner-native terminal approvals, merges outbound progress and terminal records,
 and finally reads generic facts for boundaries without a native durable record.
 The merge is deterministic across restart and rejects a cursor whose exact
-owner row has expired.
+owner row has expired. Approval and message selectors use the opaque
+`approval-decision:` and `message-decision:` namespaces minted from the same
+owner-query snapshot; raw receipt, resolution, and event identifiers never
+become selectors.
 Approval and delivery inspection never write generic duplicates. Generic fact
 writes and projections also require the full context, execution, and run tuple
 to match the immutable execution context.
diff --git a/docs/gateway/audit.md b/docs/gateway/audit.md
index 659be96fe737..376282f21b25 100644
--- a/docs/gateway/audit.md
+++ b/docs/gateway/audit.md
@@ -235,9 +235,16 @@ facts:
   authorization.
 
 The method requires `operator.read`. Requests are closed and select exactly one
-`executionId` or `runId`. Decision pages contain at most 100 receipts;
+`executionId` or `runId`. The public result always contains a required
+`decisionDisplays` array and never contains the private raw receipt array or a
+`decisions` key. The Gateway builds that result from an explicit safe-field
+allowlist; clients do not classify receipt prose. Decision pages contain at
+most 100 displays;
 ambiguous run-discovery pages contain at most 50 candidate executions. Both use
-bounded cursors.
+bounded cursors. Approval and message-delivery selectors are minted from the
+same owner-query row metadata as their projected receipts, use the
+`approval-decision:` and `message-decision:` namespaces, and never derive from
+receipt, resolution, or event identifiers.
 
 Every client with `operator.read` in the same Gateway operator domain may
 receive this retained identity category. This is intentional: the scope already
@@ -437,9 +444,11 @@ correlation alone.
   [Gateway protocol](/gateway/protocol#audit-ledger-rpc).
 - Identity RPC: `audit.run.inspect` (requires `operator.read`) accepts one
   `executionId` for exact inspection or one `runId` for bounded discovery. It
-  returns the immutable V1 context plus paged admission, approval,
-  owner-native outbound message, and generic decision receipts for an exact
-  match, or a typed ambiguous candidate page when a run has multiple executions.
+  returns the immutable V1 context plus paged safe displays for admission,
+  approval, owner-native outbound message, and generic decision records for an
+  exact match, or a typed ambiguous candidate page with an empty display array
+  when a run has multiple executions. Raw owner receipts remain private to the
+  aggregation and storage owners.
 
 ## Related
 
diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index e1e5bc3a7198..9090fb70d11f 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -409,11 +409,17 @@ The Activity tab lives in **Settings › System**, next to Logs and Debug. It ha
 
 - **Sessions** shows recent session activity grouped by day, with search, time, and people filters. Active rows offer **Inspect run** when the Gateway has recorded a run reference.
 - **Live activity** is the existing ephemeral browser-local observer for tool activity. It is derived from the same Gateway `session.tool` and tool event stream that powers Chat tool cards. It does not add another Gateway event family, endpoint, durable activity store, metrics feed, or external observer stream.
-- **Run inspector** is deep-link only and reads the Gateway's durable, immutable `audit.run.inspect` projection. Use **Inspect run** on an active session or the run ID link in Live activity, or open `/activity?view=run&run=<percent-encoded-run-id>` directly. Reloading or revisiting the link queries the Gateway again; it never reconstructs identity from Live activity.
+- **Run inspector** is deep-link only and reads the Gateway's durable, immutable `audit.run.inspect` safe-only projection. The RPC contains required `decisionDisplays` and never a raw `decisions` field. Use **Inspect run** on an active session or the run ID link in Live activity, or open `/activity?view=run&run=<percent-encoded-run-id>` directly. Reloading or revisiting the link queries the Gateway again; it never reconstructs identity from Live activity.
 
 Live activity entries keep only sanitized summaries and redacted, truncated output previews. Tool argument values are not stored in Activity state; the UI shows that arguments are hidden and records only the argument field count. The in-memory list follows the current browser tab, survives navigation within the Control UI, and resets on page reload, session switch, Gateway switch, or **Clear**.
 
-The Run inspector shows the retained trust domain, ingress, invoker, represented subject, sponsor, agent definition and principal, runtime instance, applicable grants, assurance evidence, lineage, and a bounded decision-receipt page summary. Every fact has a text evidence state. **Absent** means the owning boundary explicitly recorded no value; **unattributed** means a supported path had no usable invoker; **unknown** means expected evidence is missing or unreadable; and **unsupported** means the path has no Phase 0 evidence contract. Color is supplemental only.
+The Run inspector shows the retained trust domain, ingress, invoker, represented subject, sponsor, agent definition and principal, runtime instance, applicable grants, assurance evidence, lineage, and a bounded decision-receipt list. Every fact has a text evidence state. **Absent** means the owning boundary explicitly recorded no value; **unattributed** means a supported path had no usable invoker; **unknown** means expected evidence is missing or unreadable; and **unsupported** means the path has no Phase 0 evidence contract. Color is supplemental only.
+
+Select a receipt to see the Gateway's bounded safe-display projection: structural action and outcome fields, evidence limits, and verified display provenance. Fixed core summaries and next steps appear only when the Gateway knows the producer contract from the owning call path. Generic or otherwise unverified receipts show a structural `unknown` classification and omit their summary, remediation, and self-asserted owner metadata. Activity consumes the safe result directly: it performs no UI-side inference, post-receive stripping, or raw-receipt fallback. **Enforced** means the recorded owner changed the outcome after validating the exact context, execution, and run tuple. **Attribution only** records what happened without claiming authorization. **Unsupported** means that observation has no Phase 0 enforcement contract. The inspector displays these states as text badges as well as color and never infers a reason from another field.
+
+Receipt requests are limited to 50 records. **Load more receipts** follows the Gateway's opaque cursor and keeps earlier pages visible. A later-page error does not discard receipts already shown. Each receipt link adds `receipt=<opaque-display-selector>` and, for a later page, `decision=<opaque-cursor>` to the selected run or execution URL. The Gateway-owned selector chooses the projected display row without exposing the stored receipt identifier in the URL or as page text. Reloading that link requests the same bounded page and selects the same projected row. An expired or invalid page cursor is an explicit inspection error; choose **Restart inspection** to keep the selected run or execution and restart from the first page.
+
+Approval and message-delivery links use the `approval-decision:` and `message-decision:` selector namespaces. The owner query mints each selector from its row metadata in the same snapshot as the displayed receipt; private receipt, resolution, and event identifiers never become URL parameters.
 
 Run inspection requires `operator.read` and a Gateway that advertises `audit.run.inspect`. Execution identity collection is off by default; enable `logging.audit.executionIdentity`, restart the Gateway, and record a new run when you need this evidence. Retained contexts are limited to 30 days and 100,000 rows. A known run can therefore report unavailable or expired identity evidence, and a run reference can be ambiguous when it correlates more than one execution. The UI does not guess between executions: choose a returned candidate to navigate to `/activity?view=run&execution=<percent-encoded-execution-id>` and query that exact execution.
 
diff --git a/packages/gateway-protocol/src/public-schema.ts b/packages/gateway-protocol/src/public-schema.ts
index f4c2f8f1f487..eaa2fc9e528a 100644
--- a/packages/gateway-protocol/src/public-schema.ts
+++ b/packages/gateway-protocol/src/public-schema.ts
@@ -309,6 +309,7 @@ export {
   AuditActivityToolActionV1Schema,
   ExecutionIdentityContextV1Schema,
   DecisionReceiptV1Schema,
+  DecisionReceiptDisplayV1Schema,
   AuditRunIdentityPresentV1Schema,
   AuditRunIdentityUnknownV1Schema,
   AuditRunIdentityUnsupportedV1Schema,
diff --git a/packages/gateway-protocol/src/schema/audit-run.test.ts b/packages/gateway-protocol/src/schema/audit-run.test.ts
index eb4b965b8865..ac91e8b89264 100644
--- a/packages/gateway-protocol/src/schema/audit-run.test.ts
+++ b/packages/gateway-protocol/src/schema/audit-run.test.ts
@@ -4,6 +4,7 @@ import { validateAuditRunInspectParams, validateExecutionIdentityContextV1 } fro
 import {
   AuditRunInspectParamsSchema,
   AuditRunInspectResultSchema,
+  DecisionReceiptDisplayV1Schema,
   DecisionReceiptV1Schema,
   type ExecutionIdentityContextV1,
 } from "./audit-run.js";
@@ -88,6 +89,35 @@ describe("audit run inspection protocol", () => {
     expect(validateAuditRunInspectParams({ runId: "run-1", extra: true })).toBe(false);
   });
 
+  it("accepts only the bounded safe decision display contract", () => {
+    const validate = Compile(DecisionReceiptDisplayV1Schema);
+    const display = {
+      schemaVersion: 1,
+      selectorId: "decision-fact:1",
+      occurredAt: 1,
+      action: { family: "decision", operation: "record" },
+      decision: { outcome: "unknown", reasonCode: "decision_fact_display_unverified" },
+      enforcement: {
+        coverageState: "unknown",
+        policyCount: 1,
+        grantCount: 0,
+        contextFieldsUsed: [],
+      },
+      provenance: { state: "unverified" },
+      missingEvidence: ["decision.display_provenance"],
+      remediation: [],
+    };
+    expect(validate.Check(display)).toBe(true);
+    expect(validate.Check({ ...display, selectorId: undefined, receiptId: "hostile" })).toBe(false);
+    expect(validate.Check({ ...display, source: { owner: "operator_approvals" } })).toBe(false);
+    expect(
+      validate.Check({
+        ...display,
+        provenance: { state: "verified", producer: "receipt-owner" },
+      }),
+    ).toBe(false);
+  });
+
   it("exports selector and discovery-pagination invariants for generated clients", () => {
     const validate = Compile(AuditRunInspectParamsSchema);
 
@@ -115,12 +145,32 @@ describe("audit run inspection protocol", () => {
           missingEvidence: ["execution.selection"],
           remediation: [{ code: "select_execution_id", text: "Select one exact execution." }],
         },
-        decisions: [],
+        decisionDisplays: [],
         coverage: { state: "unknown", missingEvidence: ["execution.selection"] },
       }),
     ).toBe(true);
   });
 
+  it("exports a required safe-only decision presentation", () => {
+    const validate = Compile(AuditRunInspectResultSchema);
+    const result = {
+      schemaVersion: 1,
+      run: { runId: "run-1", status: "unknown" },
+      identity: {
+        state: "unknown",
+        reasonCode: "run_not_found",
+        missingEvidence: ["run.record"],
+        remediation: [],
+      },
+      decisionDisplays: [],
+      coverage: { state: "unknown", missingEvidence: ["run.record"] },
+    };
+
+    expect(validate.Check(result)).toBe(true);
+    expect(validate.Check({ ...result, decisionDisplays: undefined })).toBe(false);
+    expect(validate.Check({ ...result, decisions: [] })).toBe(false);
+  });
+
   it("rejects malformed, oversized, and open-ended context payloads", () => {
     expect(validateExecutionIdentityContextV1({ ...context(), extra: true })).toBe(false);
     expect(
@@ -151,7 +201,7 @@ describe("audit run inspection protocol", () => {
             missingEvidence: ["identity.context"],
             remediation: [{ code: "retry", text: "Retry after checking the run id." }],
           },
-          decisions: [],
+          decisionDisplays: [],
           coverage: { state, missingEvidence: ["identity.context"] },
         }),
       ).toBe(true);
diff --git a/packages/gateway-protocol/src/schema/audit-run.ts b/packages/gateway-protocol/src/schema/audit-run.ts
index d3cda6b5057e..fdef097116e8 100644
--- a/packages/gateway-protocol/src/schema/audit-run.ts
+++ b/packages/gateway-protocol/src/schema/audit-run.ts
@@ -202,6 +202,47 @@ export const DecisionReceiptV1Schema = closedObject({
   remediation: Type.Array(ExecutionIdentityRemediationV1Schema, { maxItems: 8 }),
 });
 
+const DecisionReceiptDisplayProvenanceV1Schema = Type.Union([
+  closedObject({
+    state: Type.Literal("verified"),
+    producer: Type.Union([
+      Type.Literal("run-admission"),
+      Type.Literal("operator-approval"),
+      Type.Literal("message-delivery"),
+    ]),
+  }),
+  closedObject({ state: Type.Literal("unverified") }),
+]);
+
+export const DecisionReceiptDisplayV1Schema = closedObject({
+  schemaVersion: Type.Literal(1),
+  selectorId: ExecutionIdentityRefSchema,
+  occurredAt: Type.Integer({ minimum: 0 }),
+  action: closedObject({
+    family: ExecutionIdentityRefSchema,
+    operation: ExecutionIdentityRefSchema,
+    summary: Type.Optional(Type.String({ maxLength: 512 })),
+  }),
+  decision: closedObject({
+    outcome: Type.Union([
+      Type.Literal("allowed"),
+      Type.Literal("denied"),
+      Type.Literal("not-applicable"),
+      Type.Literal("unknown"),
+    ]),
+    reasonCode: ExecutionIdentityRefSchema,
+  }),
+  enforcement: closedObject({
+    coverageState: ExecutionIdentityDecisionCoverageStateSchema,
+    policyCount: Type.Integer({ minimum: 0, maximum: 16 }),
+    grantCount: Type.Integer({ minimum: 0, maximum: 16 }),
+    contextFieldsUsed: ExecutionIdentityRefArraySchema,
+  }),
+  provenance: DecisionReceiptDisplayProvenanceV1Schema,
+  missingEvidence: ExecutionIdentityRefArraySchema,
+  remediation: Type.Array(ExecutionIdentityRemediationV1Schema, { maxItems: 8 }),
+});
+
 export const AuditRunIdentityPresentV1Schema = closedObject({
   state: Type.Literal("present"),
   context: ExecutionIdentityContextV1Schema,
@@ -284,7 +325,7 @@ export const AuditRunInspectResultSchema = closedObject({
     status: Type.Union([Type.Literal("known"), Type.Literal("unknown")]),
   }),
   identity: AuditRunIdentityV1Schema,
-  decisions: Type.Array(DecisionReceiptV1Schema, { maxItems: 100 }),
+  decisionDisplays: Type.Array(DecisionReceiptDisplayV1Schema, { maxItems: 100 }),
   coverage: closedObject({
     state: ExecutionIdentityDecisionCoverageStateSchema,
     missingEvidence: ExecutionIdentityRefArraySchema,
@@ -296,6 +337,7 @@ export const AuditRunInspectResultSchema = closedObject({
 export type PrincipalRefV1 = Static<typeof PrincipalRefV1Schema>;
 export type ExecutionIdentityContextV1 = Static<typeof ExecutionIdentityContextV1Schema>;
 export type DecisionReceiptV1 = Static<typeof DecisionReceiptV1Schema>;
+export type DecisionReceiptDisplayV1 = Static<typeof DecisionReceiptDisplayV1Schema>;
 export type AuditRunIdentityV1 = Static<typeof AuditRunIdentityV1Schema>;
 type AuditRunDecisionPage = {
   decisionCursor?: string;
diff --git a/packages/gateway-protocol/src/schema/protocol-schema-fragment-operations.ts b/packages/gateway-protocol/src/schema/protocol-schema-fragment-operations.ts
index 20a29d854fac..f44a175b2976 100644
--- a/packages/gateway-protocol/src/schema/protocol-schema-fragment-operations.ts
+++ b/packages/gateway-protocol/src/schema/protocol-schema-fragment-operations.ts
@@ -17,6 +17,7 @@ export const OperationsProtocolSchemas = {
   AuditActivityListResult: auditActivity.AuditActivityListResultSchema,
   ExecutionIdentityContextV1: auditRun.ExecutionIdentityContextV1Schema,
   DecisionReceiptV1: auditRun.DecisionReceiptV1Schema,
+  DecisionReceiptDisplayV1: auditRun.DecisionReceiptDisplayV1Schema,
   AuditRunIdentityPresentV1: auditRun.AuditRunIdentityPresentV1Schema,
   AuditRunIdentityUnknownV1: auditRun.AuditRunIdentityUnknownV1Schema,
   AuditRunIdentityUnsupportedV1: auditRun.AuditRunIdentityUnsupportedV1Schema,
diff --git a/src/audit/execution-decision-facts.test.ts b/src/audit/execution-decision-facts.test.ts
index c4eb64be08aa..b255e409d532 100644
--- a/src/audit/execution-decision-facts.test.ts
+++ b/src/audit/execution-decision-facts.test.ts
@@ -6,6 +6,7 @@ import {
   type ExecutionIdentityContextV1,
 } from "../../packages/gateway-protocol/src/index.js";
 import { useAutoCleanupTempDirTracker } from "../../test/helpers/temp-dir.js";
+import { activityRunInspectorSearch } from "../../ui/src/pages/activity/run-inspector-model.js";
 import { tableExists } from "../state/openclaw-state-db-schema-helpers.js";
 import {
   closeOpenClawStateDatabaseForTest,
@@ -185,7 +186,7 @@ describe("execution decision facts", () => {
     const database = databaseOptions();
     const context = seedExecutionContext(database);
     const now = Date.now();
-    recordAuditEvent(
+    const storedEvent = recordAuditEvent(
       {
         sourceId: "message:outbound:queue:delivery-1:payload:0",
         sourceSequence: 1,
@@ -208,14 +209,16 @@ describe("execution decision facts", () => {
       },
       database,
     );
+    if (!storedEvent) {
+      throw new Error("expected owner-native message event");
+    }
 
-    expect(
-      presentExecutionDecisionReceipts({
-        context,
-        decisionLimit: 10,
-        options: { ...database, now },
-      }).decisions,
-    ).toEqual(
+    const inspection = presentExecutionDecisionReceipts({
+      context,
+      decisionLimit: 10,
+      options: { ...database, now },
+    });
+    expect(inspection.decisions).toEqual(
       expect.arrayContaining([
         expect.objectContaining({
           action: expect.objectContaining({ family: "message", operation: "send" }),
@@ -225,6 +228,32 @@ describe("execution decision facts", () => {
         }),
       ]),
     );
+    expect(inspection.decisionDisplays).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          action: expect.objectContaining({ family: "message", operation: "send" }),
+          decision: { outcome: "allowed", reasonCode: "message_delivered" },
+          provenance: { state: "verified", producer: "message-delivery" },
+        }),
+      ]),
+    );
+    const messageReceipt = inspection.decisions.find((item) => item.action.family === "message");
+    const messageDisplay = inspection.decisionDisplays.find(
+      (item) =>
+        item.provenance.state === "verified" && item.provenance.producer === "message-delivery",
+    );
+    expect(messageDisplay?.selectorId).toBe(
+      `message-decision:${2_000_000_000_000 + storedEvent.sequence}`,
+    );
+    expect(messageDisplay?.selectorId).not.toBe(messageReceipt?.receiptId);
+    const receiptSearch = activityRunInspectorSearch(
+      { kind: "run", id: context.runId },
+      { id: messageDisplay?.selectorId ?? "" },
+    );
+    expect(new URLSearchParams(receiptSearch.slice(1)).get("receipt")).toBe(
+      messageDisplay?.selectorId,
+    );
+    expect(receiptSearch).not.toContain(encodeURIComponent(messageReceipt?.receiptId ?? ""));
   });
 
   it("does not assign run-only delivery evidence to either exact execution sharing a run id", () => {
@@ -420,7 +449,8 @@ describe("execution decision facts", () => {
         decisionLimit: 10,
         options: { ...database, now },
       });
-    expect(inspect().decisions.map((item) => item.decision.reasonCode)).toEqual([
+    const firstInspection = inspect();
+    expect(firstInspection.decisions.map((item) => item.decision.reasonCode)).toEqual([
       "message_queued",
       "message_platform_started",
       "message_delivered",
@@ -428,10 +458,10 @@ describe("execution decision facts", () => {
       "message_delivery_failed_platform_send",
       "message_suppressed_no_visible_payload",
     ]);
-    expect(inspect().decisions.map((item) => item.enforcement.coverageState)).toEqual(
+    expect(firstInspection.decisions.map((item) => item.enforcement.coverageState)).toEqual(
       Array.from({ length: 6 }, () => "attribution-only"),
     );
-    expect(inspect().decisions.map((item) => item.source.owner)).toEqual([
+    expect(firstInspection.decisions.map((item) => item.source.owner)).toEqual([
       "outbound_message_progress",
       "outbound_message_progress",
       "audit_events",
@@ -439,11 +469,15 @@ describe("execution decision facts", () => {
       "audit_events",
       "audit_events",
     ]);
-    expect(JSON.stringify(inspect())).not.toContain("raw-channel-target");
-    expect(JSON.stringify(inspect())).not.toContain("raw-platform-message");
+    const selectors = firstInspection.decisionDisplays.map((item) => item.selectorId);
+    expect(selectors).toHaveLength(firstInspection.decisions.length);
+    expect(new Set(selectors).size).toBe(selectors.length);
+    expect(selectors.every((selector) => selector.startsWith("message-decision:"))).toBe(true);
+    expect(JSON.stringify(firstInspection)).not.toContain("raw-channel-target");
+    expect(JSON.stringify(firstInspection)).not.toContain("raw-platform-message");
 
     closeOpenClawStateDatabaseForTest();
-    expect(inspect().decisions).toHaveLength(6);
+    expect(inspect().decisionDisplays.map((item) => item.selectorId)).toEqual(selectors);
     expect(
       presentExecutionDecisionReceipts({
         context,
@@ -550,16 +584,33 @@ describe("execution decision facts", () => {
       database,
     });
     expect(first.receipts.map((item) => item.receiptId)).toEqual(["same-time-a"]);
+    expect(first.entries).toEqual([
+      { receipt: receipt("same-time-a", 100), selectorId: "decision-fact:1" },
+    ]);
     expect(first.nextCursor).toEqual({ occurredAt: 100, rowId: expect.any(Number) });
+    const second = pageExecutionDecisionFactsForContext({
+      context: { contextId: "context-1", executionId: "execution-1", runId: "run-1" },
+      after: first.nextCursor,
+      limit: 2,
+      now: 100,
+      database,
+    });
+    expect(second.receipts.map((item) => item.receiptId)).toEqual(["same-time-b", "same-time-c"]);
+    expect(second.entries.map((entry) => entry.selectorId)).toEqual([
+      "decision-fact:2",
+      "decision-fact:3",
+    ]);
     expect(
       pageExecutionDecisionFactsForContext({
         context: { contextId: "context-1", executionId: "execution-1", runId: "run-1" },
-        after: first.nextCursor,
-        limit: 2,
+        limit: 1,
         now: 100,
         database,
-      }).receipts.map((item) => item.receiptId),
-    ).toEqual(["same-time-b", "same-time-c"]);
+      }).entries,
+    ).toEqual(first.entries);
+    expect(
+      new Set([...first.entries, ...second.entries].map((entry) => entry.selectorId)).size,
+    ).toBe(3);
 
     for (const decisionCursor of ["1", "001"]) {
       const legacyPage = presentExecutionDecisionReceipts({
@@ -569,6 +620,9 @@ describe("execution decision facts", () => {
         options: { ...database, now: 100 },
       });
       expect(legacyPage.decisions.map((item) => item.receiptId)).toEqual(["same-time-a"]);
+      expect(legacyPage.decisionDisplays?.map((item) => item.selectorId)).toEqual([
+        "decision-fact:1",
+      ]);
       expect(legacyPage.nextDecisionCursor).toMatch(/^g:/);
     }
     const legacyPage = presentExecutionDecisionReceipts({
@@ -577,17 +631,20 @@ describe("execution decision facts", () => {
       decisionLimit: 1,
       options: { ...database, now: 100 },
     });
-    expect(
-      presentExecutionDecisionReceipts({
-        context,
-        decisionCursor: legacyPage.nextDecisionCursor,
-        decisionLimit: 2,
-        options: { ...database, now: 100 },
-      }).decisions.map((item) => item.receiptId),
-    ).toEqual(["same-time-b", "same-time-c"]);
+    const next = presentExecutionDecisionReceipts({
+      context,
+      decisionCursor: legacyPage.nextDecisionCursor,
+      decisionLimit: 2,
+      options: { ...database, now: 100 },
+    });
+    expect(next.decisions.map((item) => item.receiptId)).toEqual(["same-time-b", "same-time-c"]);
+    expect(next.decisionDisplays?.map((item) => item.selectorId)).toEqual([
+      "decision-fact:2",
+      "decision-fact:3",
+    ]);
   });
 
-  it("bounds aggregated missing evidence at the result protocol boundary", () => {
+  it("replaces unverified aggregate evidence with a fixed display marker", () => {
     const database = databaseOptions();
     seedExecutionContext(database);
     const context: ExecutionIdentityContextV1 = {
@@ -627,10 +684,92 @@ describe("execution decision facts", () => {
     });
     expect(result.coverage).toEqual({
       state: "unknown",
-      missingEvidence: expect.arrayContaining(["decision.missing_evidence_truncated"]),
+      missingEvidence: expect.arrayContaining(["decision.display_provenance"]),
     });
-    expect(result.coverage.missingEvidence).toHaveLength(16);
-    expect(Compile(AuditRunInspectResultSchema).Check(result)).toBe(true);
+    expect(JSON.stringify(result.coverage)).not.toContain("one.missing");
+    expect(JSON.stringify(result.coverage)).not.toContain("two.missing");
+    expect(Compile(AuditRunInspectResultSchema).Check(result)).toBe(false);
+  });
+
+  it("keeps receipt-controlled prose out of the owner display projection", () => {
+    const database = databaseOptions();
+    const context = seedExecutionContext(database);
+    const receiptIdSecret = "U2_R6_RECEIPT_ID_SECRET_42b17d";
+    const summarySecret = "U2_R6_SUMMARY_SECRET_7c4f9a";
+    const remediationCodeSecret = "U2_R6_CODE_SECRET_81d2be";
+    const remediationTextSecret = "U2_R6_TEXT_SECRET_36a5c0";
+    const policyRefSecret = "U2_R6_POLICY_REF_SECRET_ea731c";
+    const grantRefSecret = "U2_R6_GRANT_REF_SECRET_b529f4";
+    const missingEvidenceSecret = "U2_R6_MISSING_EVIDENCE_SECRET_2d97c1";
+    recordExecutionDecisionFact(
+      {
+        ...receipt(receiptIdSecret),
+        action: {
+          family: "tool",
+          operation: "policy",
+          summary: summarySecret,
+        },
+        source: {
+          owner: "audit_events",
+          recordRef: "forged-core-looking-record",
+          decisionBoundary: "message.outbound.finished",
+        },
+        enforcement: {
+          coverageState: "enforced",
+          evaluatorRef: "forged-core-looking-evaluator",
+          policyRefs: [policyRefSecret],
+          grantRefs: [grantRefSecret],
+          contextFieldsUsed: ["runId"],
+        },
+        missingEvidence: [missingEvidenceSecret],
+        remediation: [{ code: remediationCodeSecret, text: remediationTextSecret }],
+      },
+      { ...database, now: 100 },
+    );
+
+    const result = presentExecutionDecisionReceipts({
+      context,
+      decisionLimit: 10,
+      options: { ...database, now: 100 },
+    });
+    expect(result.decisionDisplays).toBeDefined();
+    const displayJson = JSON.stringify(result.decisionDisplays);
+    expect(displayJson).not.toContain(receiptIdSecret);
+    expect(displayJson).not.toContain(summarySecret);
+    expect(displayJson).not.toContain(remediationCodeSecret);
+    expect(displayJson).not.toContain(remediationTextSecret);
+    expect(displayJson).not.toContain(policyRefSecret);
+    expect(displayJson).not.toContain(grantRefSecret);
+    expect(JSON.stringify(result.coverage)).not.toContain(missingEvidenceSecret);
+    expect(result.coverage).toEqual({
+      state: "unknown",
+      missingEvidence: expect.arrayContaining(["decision.display_provenance"]),
+    });
+    expect(JSON.stringify(result.decisions)).toContain(policyRefSecret);
+    expect(JSON.stringify(result.decisions)).toContain(grantRefSecret);
+    expect(result.decisionDisplays).toEqual([
+      expect.objectContaining({
+        action: expect.objectContaining({
+          summary: "Run admission was recorded without an identity-aware policy or grant decision.",
+        }),
+        provenance: { state: "verified", producer: "run-admission" },
+      }),
+      expect.objectContaining({
+        selectorId: "decision-fact:1",
+        action: { family: "decision", operation: "record" },
+        decision: { outcome: "unknown", reasonCode: "decision_fact_display_unverified" },
+        enforcement: {
+          coverageState: "unknown",
+          policyCount: 0,
+          grantCount: 0,
+          contextFieldsUsed: [],
+        },
+        provenance: { state: "unverified" },
+        missingEvidence: ["decision.display_provenance"],
+        remediation: [],
+      }),
+    ]);
+    expect(Compile(AuditRunInspectResultSchema).Check(result)).toBe(false);
   });
 
   it("rejects a generic fact whose context, execution, and run tuple is not exact", () => {
@@ -652,19 +791,21 @@ describe("execution decision facts", () => {
     seedExecutionContext(database);
     recordExecutionDecisionFact(receipt("tuple-mismatch"), { ...database, now: 100 });
 
-    expect(
-      pageExecutionDecisionFactsForContext({
-        context: { contextId: "context-1", executionId: "execution-2", runId: "run-1" },
-        limit: 10,
-        now: 100,
-        database,
-      }).receipts,
-    ).toEqual([
-      expect.objectContaining({
-        decision: { outcome: "unknown", reasonCode: "decision_fact_execution_link_mismatch" },
-        enforcement: expect.objectContaining({ coverageState: "unknown" }),
-        missingEvidence: ["decision.execution_link"],
-      }),
+    const page = pageExecutionDecisionFactsForContext({
+      context: { contextId: "context-1", executionId: "execution-2", runId: "run-1" },
+      limit: 10,
+      now: 100,
+      database,
+    });
+    expect(page.entries).toEqual([
+      {
+        selectorId: "decision-fact:1",
+        receipt: expect.objectContaining({
+          decision: { outcome: "unknown", reasonCode: "decision_fact_execution_link_mismatch" },
+          enforcement: expect.objectContaining({ coverageState: "unknown" }),
+          missingEvidence: ["decision.execution_link"],
+        }),
+      },
     ]);
   });
 
@@ -738,20 +879,22 @@ describe("execution decision facts", () => {
       .db.prepare("UPDATE execution_decision_facts SET receipt_json = ? WHERE receipt_id = ?")
       .run("{", "corrupt");
 
-    expect(
-      pageExecutionDecisionFactsForContext({
-        context: { contextId: "context-1", executionId: "execution-1", runId: "run-1" },
-        limit: 10,
-        now: 100,
-        database,
-      }).receipts,
-    ).toEqual([
-      expect.objectContaining({
-        receiptId: "corrupt",
-        decision: { outcome: "unknown", reasonCode: "decision_fact_record_corrupt" },
-        enforcement: expect.objectContaining({ coverageState: "unknown" }),
-        missingEvidence: ["decision.fact.valid"],
-      }),
+    const page = pageExecutionDecisionFactsForContext({
+      context: { contextId: "context-1", executionId: "execution-1", runId: "run-1" },
+      limit: 10,
+      now: 100,
+      database,
+    });
+    expect(page.entries).toEqual([
+      {
+        selectorId: "decision-fact:1",
+        receipt: expect.objectContaining({
+          receiptId: "corrupt",
+          decision: { outcome: "unknown", reasonCode: "decision_fact_record_corrupt" },
+          enforcement: expect.objectContaining({ coverageState: "unknown" }),
+          missingEvidence: ["decision.fact.valid"],
+        }),
+      },
     ]);
     expect(
       summarizeExecutionDecisionFactsForContext({
@@ -767,22 +910,23 @@ describe("execution decision facts", () => {
     expect(
       presentExecutionDecisionReceipts({
         context,
-        decisionLimit: 1,
+        decisionCursor: "g:0:0",
+        decisionLimit: 10,
         options: { ...database, now: 100 },
       }),
     ).toMatchObject({
       coverage: {
         state: "unknown",
-        missingEvidence: expect.arrayContaining(["decision.fact.valid"]),
+        missingEvidence: expect.arrayContaining(["decision.display_provenance"]),
       },
-      decisions: [{ decision: { outcome: "not-applicable" } }],
-      nextDecisionCursor: "a:0:0",
+      decisions: [{ decision: { outcome: "unknown", reasonCode: "decision_fact_record_corrupt" } }],
+      decisionDisplays: [{ selectorId: "decision-fact:1" }],
     });
   });
 
   it("does not materialize an oversized retained fact payload", () => {
     const database = databaseOptions();
-    seedExecutionContext(database);
+    const context = seedExecutionContext(database);
     recordExecutionDecisionFact(receipt("oversized"), { ...database, now: 100 });
     const db = openOpenClawStateDatabase(database).db;
     db.exec("PRAGMA ignore_check_constraints = ON");
@@ -791,18 +935,30 @@ describe("execution decision facts", () => {
       "oversized",
     );
 
-    expect(
-      pageExecutionDecisionFactsForContext({
-        context: { contextId: "context-1", executionId: "execution-1", runId: "run-1" },
-        limit: 1,
-        now: 100,
-        database,
-      }).receipts,
-    ).toEqual([
-      expect.objectContaining({
-        decision: { outcome: "unknown", reasonCode: "decision_fact_payload_bounded" },
-        missingEvidence: ["decision.fact.payload_bounded"],
-      }),
+    const page = pageExecutionDecisionFactsForContext({
+      context: { contextId: "context-1", executionId: "execution-1", runId: "run-1" },
+      limit: 1,
+      now: 100,
+      database,
+    });
+    expect(page.entries).toEqual([
+      {
+        selectorId: "decision-fact:1",
+        receipt: expect.objectContaining({
+          decision: { outcome: "unknown", reasonCode: "decision_fact_payload_bounded" },
+          missingEvidence: ["decision.fact.payload_bounded"],
+        }),
+      },
+    ]);
+    const result = presentExecutionDecisionReceipts({
+      context,
+      decisionCursor: "g:0:0",
+      decisionLimit: 1,
+      options: { ...database, now: 100 },
+    });
+    expect(result.decisions).toHaveLength(1);
+    expect(result.decisionDisplays).toEqual([
+      expect.objectContaining({ selectorId: "decision-fact:1" }),
     ]);
   });
 });
diff --git a/src/audit/execution-decision-facts.ts b/src/audit/execution-decision-facts.ts
index 713d6f08655a..55c93a1a6433 100644
--- a/src/audit/execution-decision-facts.ts
+++ b/src/audit/execution-decision-facts.ts
@@ -26,9 +26,15 @@ type ExecutionDecisionRow = Selectable<OpenClawStateKyselyDatabase["execution_de
 type ExecutionDecisionMetadataRow = Omit<ExecutionDecisionRow, "receipt_json"> & {
   receipt_rowid: number;
   payload_bytes: number;
+  bounded_receipt_json: string | null;
 };
 type ExecutionDecisionFactCursor = { occurredAt: number; rowId: number };
+type ExecutionDecisionFactPageEntry = {
+  receipt: DecisionReceiptV1;
+  selectorId: string;
+};
 type ExecutionDecisionFactPage = {
+  entries: ExecutionDecisionFactPageEntry[];
   receipts: DecisionReceiptV1[];
   nextCursor?: ExecutionDecisionFactCursor;
 };
@@ -38,6 +44,7 @@ const EXECUTION_DECISION_FACT_RETENTION_MS = 30 * 24 * 60 * 60_000;
 const EXECUTION_DECISION_FACT_MAX_ROWS = 250_000;
 const EXECUTION_DECISION_FACT_PRUNE_BATCH_ROWS = 1_024;
 const EXECUTION_DECISION_FACT_SUMMARY_MAX_ROWS = 128;
+const EXECUTION_DECISION_SELECTOR_PREFIX = "decision-fact:";
 
 const ensuredDatabases = new WeakSet<DatabaseSync>();
 
@@ -321,6 +328,20 @@ function executionDecisionPayloadBytes() {
   return /* kysely-allow-raw: SQLite byte length excludes oversized retained receipt JSON before materialization. */ sql<number>`length(CAST(execution_decision_facts.receipt_json AS BLOB))`;
 }
 
+function executionDecisionBoundedPayload() {
+  return /* kysely-allow-raw: one page snapshot returns bounded payload bytes beside the owning rowid. */ sql<
+    string | null
+  >`CASE WHEN length(CAST(execution_decision_facts.receipt_json AS BLOB)) <= ${EXECUTION_DECISION_FACT_MAX_BYTES} THEN execution_decision_facts.receipt_json ELSE NULL END`;
+}
+
+function executionDecisionSelectorId(row: ExecutionDecisionMetadataRow): string {
+  const rowId = normalizeSqliteNumber(row.receipt_rowid);
+  if (rowId === undefined || rowId < 1) {
+    throw new Error("invalid execution decision fact rowid");
+  }
+  return `${EXECUTION_DECISION_SELECTOR_PREFIX}${rowId}`;
+}
+
 function retainedDecisionFactMetadata(params: {
   db: DatabaseSync;
   contextId: string;
@@ -375,6 +396,7 @@ function retainedDecisionFactMetadata(params: {
       .select([
         executionDecisionRowId().as("receipt_rowid"),
         executionDecisionPayloadBytes().as("payload_bytes"),
+        executionDecisionBoundedPayload().as("bounded_receipt_json"),
       ])
       .orderBy("occurred_at", "asc")
       .orderBy("receipt_id", "asc")
@@ -383,24 +405,6 @@ function retainedDecisionFactMetadata(params: {
   ).rows;
 }
 
-function retainedDecisionFactRowsById(
-  db: DatabaseSync,
-  ids: readonly string[],
-): Map<string, ExecutionDecisionRow> {
-  if (ids.length === 0) {
-    return new Map();
-  }
-  const rows = executeSqliteQuerySync(
-    db,
-    decisionDb(db)
-      .selectFrom("execution_decision_facts")
-      .selectAll()
-      .where("receipt_id", "in", [...ids])
-      .where(executionDecisionPayloadBytes(), "<=", EXECUTION_DECISION_FACT_MAX_BYTES),
-  ).rows;
-  return new Map(rows.map((row) => [row.receipt_id, row]));
-}
-
 function projectDecisionRow(
   row: ExecutionDecisionRow,
   context: ExecutionDecisionContext,
@@ -421,6 +425,22 @@ function projectDecisionRow(
   }
 }
 
+function projectDecisionMetadata(
+  metadata: ExecutionDecisionMetadataRow,
+  context: ExecutionDecisionContext,
+): DecisionReceiptV1 {
+  if (metadata.payload_bytes > EXECUTION_DECISION_FACT_MAX_BYTES) {
+    return unknownDecisionReceipt(
+      metadata,
+      "decision_fact_payload_bounded",
+      "decision.fact.payload_bounded",
+    );
+  }
+  return typeof metadata.bounded_receipt_json === "string"
+    ? projectDecisionRow({ ...metadata, receipt_json: metadata.bounded_receipt_json }, context)
+    : unknownDecisionReceipt(metadata, "decision_fact_record_corrupt", "decision.fact.valid");
+}
+
 /** Summarize at most 128 owner rows; the 129th makes coverage explicitly unknown. */
 export function summarizeExecutionDecisionFactsForContext(params: {
   context: ExecutionDecisionContext;
@@ -455,25 +475,9 @@ export function summarizeExecutionDecisionFactsForContext(params: {
           missingEvidence: ["decision.fact.summary_bounded"],
         };
       }
-      const rowsById = retainedDecisionFactRowsById(
-        db,
-        metadataRows
-          .filter((row) => row.payload_bytes <= EXECUTION_DECISION_FACT_MAX_BYTES)
-          .map((row) => row.receipt_id),
+      const receipts = metadataRows.map((metadata) =>
+        projectDecisionMetadata(metadata, params.context),
       );
-      const receipts = metadataRows.map((metadata) => {
-        if (metadata.payload_bytes > EXECUTION_DECISION_FACT_MAX_BYTES) {
-          return unknownDecisionReceipt(
-            metadata,
-            "decision_fact_payload_bounded",
-            "decision.fact.payload_bounded",
-          );
-        }
-        const row = rowsById.get(metadata.receipt_id);
-        return row
-          ? projectDecisionRow(row, params.context)
-          : unknownDecisionReceipt(metadata, "decision_fact_record_corrupt", "decision.fact.valid");
-      });
       const coverage = new Set(receipts.map((receipt) => receipt.enforcement.coverageState));
       return {
         count,
@@ -532,7 +536,7 @@ export function pageExecutionDecisionFactsForContext(params: {
   return (
     withExistingOpenClawStateDatabaseReadOnly(({ db }) => {
       if (!tableExists(db, "execution_decision_facts")) {
-        return { receipts: [] };
+        return { entries: [], receipts: [] };
       }
       const metadataRows = retainedDecisionFactMetadata({
         db,
@@ -543,28 +547,14 @@ export function pageExecutionDecisionFactsForContext(params: {
         limit: params.limit + 1,
       });
       const pageMetadata = metadataRows.slice(0, params.limit);
-      const rowsById = retainedDecisionFactRowsById(
-        db,
-        pageMetadata
-          .filter((row) => row.payload_bytes <= EXECUTION_DECISION_FACT_MAX_BYTES)
-          .map((row) => row.receipt_id),
-      );
-      const receipts = pageMetadata.map((metadata) => {
-        if (metadata.payload_bytes > EXECUTION_DECISION_FACT_MAX_BYTES) {
-          return unknownDecisionReceipt(
-            metadata,
-            "decision_fact_payload_bounded",
-            "decision.fact.payload_bounded",
-          );
-        }
-        const row = rowsById.get(metadata.receipt_id);
-        return row
-          ? projectDecisionRow(row, params.context)
-          : unknownDecisionReceipt(metadata, "decision_fact_record_corrupt", "decision.fact.valid");
-      });
+      const entries = pageMetadata.map((metadata) => ({
+        receipt: projectDecisionMetadata(metadata, params.context),
+        selectorId: executionDecisionSelectorId(metadata),
+      }));
       const last = pageMetadata.at(-1);
       return {
-        receipts,
+        entries,
+        receipts: entries.map((entry) => entry.receipt),
         ...(metadataRows.length > params.limit && last
           ? {
               nextCursor: {
@@ -574,7 +564,7 @@ export function pageExecutionDecisionFactsForContext(params: {
             }
           : {}),
       };
-    }, params.database) ?? { receipts: [] }
+    }, params.database) ?? { entries: [], receipts: [] }
   );
 }
 
diff --git a/src/audit/execution-decision-receipts.ts b/src/audit/execution-decision-receipts.ts
index 9f339d6384a7..ec65124afda2 100644
--- a/src/audit/execution-decision-receipts.ts
+++ b/src/audit/execution-decision-receipts.ts
@@ -1,6 +1,7 @@
 /** Bounded receipt projection across admission, owner-native, and generic decision facts. */
 import type {
   AuditRunInspectResult,
+  DecisionReceiptDisplayV1,
   DecisionReceiptV1,
   ExecutionIdentityContextV1,
 } from "../../packages/gateway-protocol/src/index.js";
@@ -21,6 +22,16 @@ import {
 
 type ExecutionDecisionReadOptions = OpenClawStateDatabaseOptions & { now?: number };
 
+export type InternalAuditRunInspectResult = AuditRunInspectResult & {
+  decisions: DecisionReceiptV1[];
+};
+
+type ProvenancedDecisionReceipt = {
+  receipt: DecisionReceiptV1;
+  provenance: DecisionReceiptDisplayV1["provenance"];
+  selectorId: string;
+};
+
 const MAX_AGGREGATE_MISSING_EVIDENCE = 16;
 const MISSING_EVIDENCE_TRUNCATED = "decision.missing_evidence_truncated";
 type DecisionCursor =
@@ -131,12 +142,60 @@ function admissionDecision(context: ExecutionIdentityContextV1): DecisionReceipt
   };
 }
 
+function projectDecisionDisplay({
+  receipt,
+  provenance,
+  selectorId,
+}: ProvenancedDecisionReceipt): DecisionReceiptDisplayV1 {
+  if (provenance.state === "unverified") {
+    return {
+      schemaVersion: 1,
+      selectorId,
+      occurredAt: receipt.occurredAt,
+      action: { family: "decision", operation: "record" },
+      decision: { outcome: "unknown", reasonCode: "decision_fact_display_unverified" },
+      enforcement: {
+        coverageState: "unknown",
+        policyCount: 0,
+        grantCount: 0,
+        contextFieldsUsed: [],
+      },
+      provenance,
+      missingEvidence: ["decision.display_provenance"],
+      remediation: [],
+    };
+  }
+  const counts = {
+    policyCount: receipt.enforcement.policyRefs.length,
+    grantCount: receipt.enforcement.grantRefs.length,
+  };
+  return {
+    schemaVersion: 1,
+    selectorId,
+    occurredAt: receipt.occurredAt,
+    action: {
+      family: receipt.action.family,
+      operation: receipt.action.operation,
+      ...(receipt.action.summary ? { summary: receipt.action.summary } : {}),
+    },
+    decision: receipt.decision,
+    enforcement: {
+      coverageState: receipt.enforcement.coverageState,
+      ...counts,
+      contextFieldsUsed: receipt.enforcement.contextFieldsUsed,
+    },
+    provenance,
+    missingEvidence: receipt.missingEvidence,
+    remediation: receipt.remediation,
+  };
+}
+
 export function presentExecutionDecisionReceipts(params: {
   context: ExecutionIdentityContextV1;
   decisionCursor?: string;
   decisionLimit?: number;
   options: ExecutionDecisionReadOptions;
-}): AuditRunInspectResult {
+}): InternalAuditRunInspectResult {
   const cursor = parseDecisionCursor(params.decisionCursor);
   if (cursor === null) {
     throw new ExecutionDecisionCursorError();
@@ -166,14 +225,18 @@ export function presentExecutionDecisionReceipts(params: {
     context: params.context,
     options: { ...params.options, now },
   });
-  const decisions: DecisionReceiptV1[] = [];
+  const decisions: ProvenancedDecisionReceipt[] = [];
   let remainingLimit = limit;
   let nextDecisionCursor: string | undefined;
   const approvalOffset =
     legacyOffset !== undefined && legacyOffset < approvalSummary.count ? legacyOffset : undefined;
 
   if (cursor === undefined && remainingLimit > 0) {
-    decisions.push(admissionDecision(params.context));
+    decisions.push({
+      receipt: admissionDecision(params.context),
+      provenance: { state: "verified", producer: "run-admission" },
+      selectorId: `${params.context.contextId}:admission`,
+    });
     remainingLimit -= 1;
     if (
       remainingLimit === 0 &&
@@ -210,8 +273,14 @@ export function presentExecutionDecisionReceipts(params: {
       }
       throw error;
     }
-    decisions.push(...page.receipts);
-    remainingLimit -= page.receipts.length;
+    decisions.push(
+      ...page.entries.map((entry) => ({
+        receipt: entry.receipt,
+        provenance: { state: "verified" as const, producer: "operator-approval" as const },
+        selectorId: entry.selectorId,
+      })),
+    );
+    remainingLimit -= page.entries.length;
     if (page.nextCursor) {
       nextDecisionCursor = formatDecisionCursor("approval", page.nextCursor);
     } else if (remainingLimit === 0 && messageSummary.count > 0) {
@@ -250,8 +319,14 @@ export function presentExecutionDecisionReceipts(params: {
       }
       throw error;
     }
-    decisions.push(...page.receipts);
-    remainingLimit -= page.receipts.length;
+    decisions.push(
+      ...page.entries.map((entry) => ({
+        receipt: entry.receipt,
+        provenance: { state: "verified" as const, producer: "message-delivery" as const },
+        selectorId: entry.selectorId,
+      })),
+    );
+    remainingLimit -= page.entries.length;
     if (page.nextCursor) {
       nextDecisionCursor = formatDecisionCursor("message", page.nextCursor);
     } else if (remainingLimit === 0 && genericSummary.count > 0) {
@@ -285,28 +360,31 @@ export function presentExecutionDecisionReceipts(params: {
       }
       throw error;
     }
-    decisions.push(...page.receipts);
+    decisions.push(
+      ...page.entries.map((entry) => ({
+        receipt: entry.receipt,
+        provenance: { state: "unverified" as const },
+        selectorId: entry.selectorId,
+      })),
+    );
     if (page.nextCursor) {
       nextDecisionCursor = formatDecisionCursor("generic", page.nextCursor);
     } else {
       nextDecisionCursor = undefined;
     }
   }
-  const ownerCoverage = new Set([
-    approvalSummary.coverageState,
-    messageSummary.coverageState,
-    genericSummary.coverageState,
-  ]);
+  const ownerCoverage = new Set([approvalSummary.coverageState, messageSummary.coverageState]);
+  const hasUnverifiedGenericDecisions = genericSummary.count > 0;
   const boundedEvidence = boundMissingEvidence([
     ...params.context.missingEvidence,
     ...approvalSummary.missingEvidence,
     ...messageSummary.missingEvidence,
-    ...genericSummary.missingEvidence,
+    ...(hasUnverifiedGenericDecisions ? ["decision.display_provenance"] : []),
   ]);
   const coverageState = boundedEvidence.truncated
     ? "unknown"
-    : ownerCoverage.has("unsupported")
-      ? "unsupported"
+    : hasUnverifiedGenericDecisions
+      ? "unknown"
       : ownerCoverage.has("unknown")
         ? "unknown"
         : ownerCoverage.has("enforced")
@@ -322,7 +400,8 @@ export function presentExecutionDecisionReceipts(params: {
       status: "known",
     },
     identity: { state: "present", context: params.context },
-    decisions,
+    decisions: decisions.map(({ receipt }) => receipt),
+    decisionDisplays: decisions.map(projectDecisionDisplay),
     coverage: { state: coverageState, missingEvidence: boundedEvidence.missingEvidence },
     ...(nextDecisionCursor ? { nextDecisionCursor } : {}),
   };
diff --git a/src/audit/execution-identity-context.ts b/src/audit/execution-identity-context.ts
index f4287438868f..f4c31ade8134 100644
--- a/src/audit/execution-identity-context.ts
+++ b/src/audit/execution-identity-context.ts
@@ -1,10 +1,7 @@
 /** Immutable execution identity context storage and run-admission projection. */
 import type { DatabaseSync } from "node:sqlite";
 import type { Selectable } from "kysely";
-import type {
-  AuditRunInspectResult,
-  ExecutionIdentityContextV1,
-} from "../../packages/gateway-protocol/src/index.js";
+import type { ExecutionIdentityContextV1 } from "../../packages/gateway-protocol/src/index.js";
 import { validateExecutionIdentityContextV1 } from "../../packages/gateway-protocol/src/index.js";
 import { hasOperatorApprovalReceiptsForRun } from "../gateway/operator-approval-store.js";
 import {
@@ -23,7 +20,10 @@ import {
 } from "../state/openclaw-state-db.js";
 import { clearAuditIdentityKeyCacheForDatabase } from "./audit-identity.js";
 import { hasExecutionDecisionFactsForRun } from "./execution-decision-facts.js";
-import { presentExecutionDecisionReceipts } from "./execution-decision-receipts.js";
+import {
+  presentExecutionDecisionReceipts,
+  type InternalAuditRunInspectResult,
+} from "./execution-decision-receipts.js";
 import {
   parseExecutionIdentityAdmissionEnvelope,
   parseExecutionIdentityAdmissionWork,
@@ -391,8 +391,8 @@ function unavailableResult(params: {
   reasonCode: string;
   missingEvidence: string[];
   remediation: Array<{ code: string; text: string }>;
-}): AuditRunInspectResult {
-  const run: AuditRunInspectResult["run"] =
+}): InternalAuditRunInspectResult {
+  const run: InternalAuditRunInspectResult["run"] =
     "executionId" in params.selector
       ? {
           executionId: params.selector.executionId,
@@ -413,6 +413,7 @@ function unavailableResult(params: {
       remediation: params.remediation,
     },
     decisions: [],
+    decisionDisplays: [],
     coverage: { state: params.state, missingEvidence: params.missingEvidence },
   };
 }
@@ -421,7 +422,7 @@ function unavailableIdentityContext(
   selector: { runId: string } | { executionId: string },
   remediation: { code: string; text: string },
   resolvedRunId?: string,
-): AuditRunInspectResult {
+): InternalAuditRunInspectResult {
   return unavailableResult({
     selector,
     resolvedRunId,
@@ -436,7 +437,7 @@ function unavailableIdentityContext(
 function inspectExactExecution(
   params: { executionId: string; decisionCursor?: string; decisionLimit?: number },
   options: ExecutionIdentityReadOptions,
-): AuditRunInspectResult {
+): InternalAuditRunInspectResult {
   const executionId = ensureBoundedExecutionIdentityRef(params.executionId, "execution id");
   const selector = { executionId };
   const contextResult = readExecutionIdentityContextByExecutionId(executionId, options);
@@ -529,125 +530,125 @@ function inspectRunSelector(
     decisionLimit?: number;
   },
   options: ExecutionIdentityReadOptions,
-): AuditRunInspectResult {
+): InternalAuditRunInspectResult {
   const runId = ensureBoundedExecutionIdentityRef(params.runId, "run id");
   const now = options.now ?? Date.now();
-  const inspected = withExistingOpenClawStateDatabaseReadOnly<AuditRunInspectResult | undefined>(
-    ({ db }) => {
-      const firstMatches = tableExists(db, "execution_identity_contexts")
-        ? readRowsByRunId(db, runId, now, 0, 2)
-        : [];
-      if (firstMatches.length === 1) {
-        let context: ExecutionIdentityContextV1;
-        try {
-          context = parseExecutionIdentityRow(firstMatches[0]!);
-        } catch {
-          return unavailableResult({
-            selector: { runId },
-            runStatus: "known",
-            state: "unknown",
-            reasonCode: "identity_context_corrupt",
-            missingEvidence: ["identity.context.valid"],
-            remediation: [
-              {
-                code: "inspect_state_integrity",
-                text: "Run openclaw doctor and inspect the shared state database before trusting this run.",
-              },
-            ],
-          });
-        }
-        return presentExecutionDecisionReceipts({
-          context,
-          decisionCursor: params.decisionCursor,
-          decisionLimit: params.decisionLimit,
-          options,
-        });
-      }
-      if (firstMatches.length > 1) {
-        const offset = params.executionOffset ?? 0;
-        const limit = params.executionLimit ?? 50;
-        const page = readRowsByRunId(db, runId, now, offset, limit + 1);
-        const candidates = page.slice(0, limit).map((row) => ({
-          executionId: row.execution_id,
-          contextId: row.context_id,
-          createdAt: normalizeSqliteNumber(row.created_at) ?? 0,
-        }));
-        return {
-          schemaVersion: 1,
-          run: { runId, status: "known" },
-          identity: {
-            state: "ambiguous",
-            reasonCode: "execution_selection_required",
-            candidates,
-            missingEvidence: ["execution.selection"],
-            remediation: [
-              {
-                code: "select_execution_id",
-                text: "Select one candidate with openclaw audit --execution <id> --explain.",
-              },
-            ],
-          },
-          decisions: [],
-          coverage: { state: "unknown", missingEvidence: ["execution.selection"] },
-          ...(page.length > limit ? { nextExecutionCursor: String(offset + limit) } : {}),
-        };
-      }
-      if (
-        hasOperatorApprovalReceiptsForRun({ runId, nowMs: now, databaseOptions: options }) ||
-        hasExecutionDecisionFactsForRun({ runId, now, database: options })
-      ) {
+  const inspected = withExistingOpenClawStateDatabaseReadOnly<
+    InternalAuditRunInspectResult | undefined
+  >(({ db }) => {
+    const firstMatches = tableExists(db, "execution_identity_contexts")
+      ? readRowsByRunId(db, runId, now, 0, 2)
+      : [];
+    if (firstMatches.length === 1) {
+      let context: ExecutionIdentityContextV1;
+      try {
+        context = parseExecutionIdentityRow(firstMatches[0]!);
+      } catch {
         return unavailableResult({
           selector: { runId },
           runStatus: "known",
           state: "unknown",
-          reasonCode: "decision_context_link_missing",
-          missingEvidence: ["identity.context", "decision.context_link"],
-          remediation: [
-            {
-              code: "record_new_identity_context",
-              text: "Confirm execution identity collection is enabled, then run and request the action again to record a linked context.",
-            },
-          ],
-        });
-      }
-      if (tableExists(db, "execution_identity_contexts") && hasAnyRunContext(db, runId)) {
-        return unavailableIdentityContext(
-          { runId },
-          {
-            code: "run_again_after_expiry",
-            text: "This run's retained identity contexts are outside the 30-day window; run the operation again to record a new execution.",
-          },
-        );
-      }
-      try {
-        if (hasRetainedAuditRun(db, runId, now)) {
-          return unavailableIdentityContext(
-            { runId },
-            {
-              code: "record_new_identity_context",
-              text: "Confirm audit collection is enabled and the Gateway is current, then run the operation again to record a new execution context.",
-            },
-          );
-        }
-      } catch {
-        return unavailableResult({
-          selector: { runId },
-          runStatus: "unknown",
-          state: "unknown",
-          reasonCode: "run_evidence_unreadable",
-          missingEvidence: ["run.record", "identity.context"],
+          reasonCode: "identity_context_corrupt",
+          missingEvidence: ["identity.context.valid"],
           remediation: [
             {
               code: "inspect_state_integrity",
-              text: "Run openclaw doctor and retry the run inspection.",
+              text: "Run openclaw doctor and inspect the shared state database before trusting this run.",
             },
           ],
         });
       }
-      return undefined;
-    },
-    options,
-  );
+      return presentExecutionDecisionReceipts({
+        context,
+        decisionCursor: params.decisionCursor,
+        decisionLimit: params.decisionLimit,
+        options,
+      });
+    }
+    if (firstMatches.length > 1) {
+      const offset = params.executionOffset ?? 0;
+      const limit = params.executionLimit ?? 50;
+      const page = readRowsByRunId(db, runId, now, offset, limit + 1);
+      const candidates = page.slice(0, limit).map((row) => ({
+        executionId: row.execution_id,
+        contextId: row.context_id,
+        createdAt: normalizeSqliteNumber(row.created_at) ?? 0,
+      }));
+      return {
+        schemaVersion: 1,
+        run: { runId, status: "known" },
+        identity: {
+          state: "ambiguous",
+          reasonCode: "execution_selection_required",
+          candidates,
+          missingEvidence: ["execution.selection"],
+          remediation: [
+            {
+              code: "select_execution_id",
+              text: "Select one candidate with openclaw audit --execution <id> --explain.",
+            },
+          ],
+        },
+        decisions: [],
+        decisionDisplays: [],
+        coverage: { state: "unknown", missingEvidence: ["execution.selection"] },
+        ...(page.length > limit ? { nextExecutionCursor: String(offset + limit) } : {}),
+      };
+    }
+    if (
+      hasOperatorApprovalReceiptsForRun({ runId, nowMs: now, databaseOptions: options }) ||
+      hasExecutionDecisionFactsForRun({ runId, now, database: options })
+    ) {
+      return unavailableResult({
+        selector: { runId },
+        runStatus: "known",
+        state: "unknown",
+        reasonCode: "decision_context_link_missing",
+        missingEvidence: ["identity.context", "decision.context_link"],
+        remediation: [
+          {
+            code: "record_new_identity_context",
+            text: "Confirm execution identity collection is enabled, then run and request the action again to record a linked context.",
+          },
+        ],
+      });
+    }
+    if (tableExists(db, "execution_identity_contexts") && hasAnyRunContext(db, runId)) {
+      return unavailableIdentityContext(
+        { runId },
+        {
+          code: "run_again_after_expiry",
+          text: "This run's retained identity contexts are outside the 30-day window; run the operation again to record a new execution.",
+        },
+      );
+    }
+    try {
+      if (hasRetainedAuditRun(db, runId, now)) {
+        return unavailableIdentityContext(
+          { runId },
+          {
+            code: "record_new_identity_context",
+            text: "Confirm audit collection is enabled and the Gateway is current, then run the operation again to record a new execution context.",
+          },
+        );
+      }
+    } catch {
+      return unavailableResult({
+        selector: { runId },
+        runStatus: "unknown",
+        state: "unknown",
+        reasonCode: "run_evidence_unreadable",
+        missingEvidence: ["run.record", "identity.context"],
+        remediation: [
+          {
+            code: "inspect_state_integrity",
+            text: "Run openclaw doctor and retry the run inspection.",
+          },
+        ],
+      });
+    }
+    return undefined;
+  }, options);
   if (inspected) {
     return inspected;
   }
@@ -678,7 +679,7 @@ export function inspectExecutionIdentityRun(
       }
     | { executionId: string; decisionCursor?: string; decisionLimit?: number },
   options: ExecutionIdentityReadOptions = {},
-): AuditRunInspectResult {
+): InternalAuditRunInspectResult {
   return "executionId" in params
     ? inspectExactExecution(params, options)
     : inspectRunSelector(params, options);
diff --git a/src/audit/message-delivery-audit-store.ts b/src/audit/message-delivery-audit-store.ts
index f9b0b8474a50..2676a1f7c2eb 100644
--- a/src/audit/message-delivery-audit-store.ts
+++ b/src/audit/message-delivery-audit-store.ts
@@ -282,7 +282,7 @@ export function pageOutboundMessageAuditEventsForRun(params: {
   limit: number;
   now?: number;
   database?: OpenClawStateDatabaseOptions;
-}): { events: OutboundMessageAuditEventRecord[]; nextCursor?: OutboundMessageAuditEventCursor } {
+}): { entries: OwnedMessageEvent[]; nextCursor?: OutboundMessageAuditEventCursor } {
   if (params.after) {
     const stage = Math.floor(params.after.rowId / MESSAGE_CURSOR_STAGE_SPAN);
     const sequence = params.after.rowId % MESSAGE_CURSOR_STAGE_SPAN;
@@ -339,7 +339,7 @@ export function pageOutboundMessageAuditEventsForRun(params: {
   const pageRows = rows.slice(0, params.limit);
   const last = pageRows.at(-1);
   return {
-    events: pageRows.map((item) => item.event),
+    entries: pageRows,
     ...(rows.length > params.limit && last
       ? { nextCursor: { occurredAt: last.event.occurredAt, rowId: last.rowId } }
       : {}),
diff --git a/src/audit/message-delivery-progress-store.test.ts b/src/audit/message-delivery-progress-store.test.ts
index 666452c5c025..32d16a4a46e9 100644
--- a/src/audit/message-delivery-progress-store.test.ts
+++ b/src/audit/message-delivery-progress-store.test.ts
@@ -218,7 +218,7 @@ describe("outbound message progress companion", () => {
       now: occurredAt,
       limit: 1,
     });
-    expect(first.events).toHaveLength(1);
+    expect(first.entries).toHaveLength(1);
     expect(first.nextCursor).toBeDefined();
     closeOpenClawStateDatabaseForTest();
 
@@ -229,9 +229,19 @@ describe("outbound message progress companion", () => {
       after: first.nextCursor,
       limit: 2,
     });
-    const all = [...first.events, ...second.events];
+    const allEntries = [...first.entries, ...second.entries];
+    const all = allEntries.map((entry) => entry.event);
     expect(all.map((event) => event.outcome)).toEqual(["queued", "platform_started", "sent"]);
     expect(new Set(all.map((event) => event.eventId)).size).toBe(3);
+    expect(new Set(allEntries.map((entry) => entry.rowId)).size).toBe(3);
+    expect(
+      pageOutboundMessageAuditEventsForRun({
+        runId: "run-progress",
+        database,
+        now: occurredAt,
+        limit: 3,
+      }).entries,
+    ).toEqual(allEntries);
     expect(
       countOutboundMessageAuditEventsForRun({ runId: "run-progress", database, now: occurredAt }),
     ).toBe(3);
@@ -349,7 +359,7 @@ describe("outbound message progress companion", () => {
         database,
         now: occurredAt,
         limit: 10,
-      }).events.map((event) => event.outcome),
+      }).entries.map((entry) => entry.event.outcome),
     ).toEqual(["queued", "platform_started", "sent"]);
     // A pinned-SHA worktree plus a cold tsx compile of the audit/state modules costs
     // minutes on a contended runner; the 120s default makes this fail by construction.
@@ -402,7 +412,7 @@ describe("outbound message progress companion", () => {
       offset: 510,
       limit: 4,
     });
-    expect(page.events.map((event) => event.outcome)).toEqual([
+    expect(page.entries.map((entry) => entry.event.outcome)).toEqual([
       "queued",
       "platform_started",
       "queued",
@@ -416,7 +426,7 @@ describe("outbound message progress companion", () => {
         now: occurredAt,
         after: page.nextCursor,
         limit: 2,
-      }).events.map((event) => event.outcome),
+      }).entries.map((entry) => entry.event.outcome),
     ).toEqual(["queued", "platform_started"]);
   });
 
@@ -434,11 +444,11 @@ describe("outbound message progress companion", () => {
       now: occurredAt,
       limit: 2,
     });
-    const progress = first.events.find((event) => event.outcome === "queued");
+    const progress = first.entries.find((entry) => entry.event.outcome === "queued");
     expect(progress).toBeDefined();
     const progressCursor = {
       occurredAt,
-      rowId: progress?.sequence ?? 0,
+      rowId: progress?.rowId ?? 0,
     };
     openOpenClawStateDatabase(database).db.prepare("DELETE FROM outbound_message_progress").run();
 
@@ -457,7 +467,7 @@ describe("outbound message progress companion", () => {
         database,
         now: occurredAt,
         limit: 10,
-      }).events.map((event) => event.outcome),
+      }).entries.map((entry) => entry.event.outcome),
     ).toEqual(["sent"]);
   });
 
diff --git a/src/audit/message-delivery-receipts.ts b/src/audit/message-delivery-receipts.ts
index 78ff2760faa4..e3ee7be0b096 100644
--- a/src/audit/message-delivery-receipts.ts
+++ b/src/audit/message-delivery-receipts.ts
@@ -151,7 +151,10 @@ export function pageMessageDeliveryReceiptsForRun(params: {
   offset?: number;
   limit: number;
   options: MessageDeliveryReadOptions;
-}): { receipts: DecisionReceiptV1[]; nextCursor?: OutboundMessageAuditEventCursor } {
+}): {
+  entries: Array<{ receipt: DecisionReceiptV1; selectorId: string }>;
+  nextCursor?: OutboundMessageAuditEventCursor;
+} {
   const page = pageOutboundMessageAuditEventsForRun({
     runId: params.context.runId,
     contextId: params.context.contextId,
@@ -163,7 +166,10 @@ export function pageMessageDeliveryReceiptsForRun(params: {
     database: params.options,
   });
   return {
-    receipts: page.events.map((event) => projectMessageDeliveryReceipt(event, params.context)),
+    entries: page.entries.map(({ event, rowId }) => ({
+      receipt: projectMessageDeliveryReceipt(event, params.context),
+      selectorId: `message-decision:${rowId}`,
+    })),
     ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
   };
 }
diff --git a/src/commands/audit.test.ts b/src/commands/audit.test.ts
index 524628105280..c20c4467ca59 100644
--- a/src/commands/audit.test.ts
+++ b/src/commands/audit.test.ts
@@ -415,7 +415,7 @@ describe("audit run explanation", () => {
         missingEvidence: ["run.record"],
         remediation: [],
       },
-      decisions: [],
+      decisionDisplays: [],
       coverage: { state: "unknown", missingEvidence: ["run.record"] },
     });
 
@@ -456,6 +456,15 @@ describe("audit run explanation", () => {
 
   it("queries audit.run.inspect and renders all identity fields with explicit state", async () => {
     const hmacRef = `hmac-sha256:v1:${"a".repeat(32)}:${"b".repeat(64)}`;
+    const hostileRawReceiptSecrets = [
+      "U2_R6_CLI_RECEIPT_ID_SECRET_97af31",
+      "U2_R6_CLI_SUMMARY_SECRET_ba9180",
+      "U2_R6_CLI_CODE_SECRET_f26d43",
+      "U2_R6_CLI_TEXT_SECRET_0c75ee",
+      "U2_R6_CLI_POLICY_REF_SECRET_2bd706",
+      "U2_R6_CLI_GRANT_REF_SECRET_a14c83",
+      "U2_R6_CLI_FORGED_OWNER_SECRET_3f4e21",
+    ];
     callGateway.mockResolvedValue({
       schemaVersion: 1,
       run: { runId: "run-1", executionId: "execution-1", status: "known" },
@@ -497,13 +506,10 @@ describe("audit run explanation", () => {
           missingEvidence: ["invoker.principal"],
         },
       },
-      decisions: [
+      decisionDisplays: [
         {
           schemaVersion: 1,
-          receiptId: "context-1:admission",
-          contextId: "context-1",
-          executionId: "execution-1",
-          runId: "run-1",
+          selectorId: "context-1:admission",
           occurredAt: 1,
           action: { family: "run", operation: "admission" },
           decision: {
@@ -512,25 +518,17 @@ describe("audit run explanation", () => {
           },
           enforcement: {
             coverageState: "unattributed",
-            policyRefs: [],
-            grantRefs: [],
+            policyCount: 0,
+            grantCount: 0,
             contextFieldsUsed: [],
           },
-          source: {
-            owner: "agent-command",
-            recordRef: "context-1",
-            decisionBoundary: "agent-command.run-admission",
-          },
+          provenance: { state: "verified", producer: "run-admission" },
           missingEvidence: ["invoker.principal"],
           remediation: [{ code: "no_claim", text: "Treat this receipt as attribution only." }],
         },
         {
           schemaVersion: 1,
-          receiptId: "approval:receipt-1",
-          contextId: "context-1",
-          executionId: "execution-1",
-          runId: "run-1",
-          actionId: "receipt-1",
+          selectorId: "approval-decision:1",
           occurredAt: 2,
           action: { family: "exec", operation: "approval" },
           decision: {
@@ -539,41 +537,29 @@ describe("audit run explanation", () => {
           },
           enforcement: {
             coverageState: "enforced",
-            evaluatorRef: "operator-approval:device",
-            policyRefs: ["operator-approval:human-decision"],
-            grantRefs: [],
+            policyCount: 1,
+            grantCount: 0,
             contextFieldsUsed: ["contextId", "executionId", "runId"],
           },
-          source: {
-            owner: "operator_approvals",
-            recordRef: "receipt-1",
-            decisionBoundary: "gateway.operator-approval.first-answer",
-          },
+          provenance: { state: "verified", producer: "operator-approval" },
           missingEvidence: [],
           remediation: [{ code: "review_and_request_again", text: "Review the denial and retry." }],
         },
         {
           schemaVersion: 1,
-          receiptId: "fact-corrupt",
-          contextId: "context-1",
-          executionId: "execution-1",
-          runId: "run-1",
+          selectorId: "decision-fact:1",
           occurredAt: 3,
-          action: { family: "tool", operation: "decision" },
-          decision: { outcome: "unknown", reasonCode: "decision_fact_record_corrupt" },
+          action: { family: "decision", operation: "record" },
+          decision: { outcome: "unknown", reasonCode: "decision_fact_display_unverified" },
           enforcement: {
             coverageState: "unknown",
-            policyRefs: [],
-            grantRefs: [],
+            policyCount: 0,
+            grantCount: 0,
             contextFieldsUsed: [],
           },
-          source: {
-            owner: "tool-policy",
-            recordRef: "fact-corrupt",
-            decisionBoundary: "execution-decision-facts",
-          },
-          missingEvidence: ["decision.fact.valid"],
-          remediation: [{ code: "inspect_state_integrity", text: "Inspect state integrity." }],
+          provenance: { state: "unverified" },
+          missingEvidence: ["decision.display_provenance"],
+          remediation: [],
         },
       ],
       coverage: { state: "enforced", missingEvidence: ["invoker.principal"] },
@@ -617,10 +603,26 @@ describe("audit run explanation", () => {
     expect(output).toContain("operator_approval_denied_by_reviewer");
     expect(output).toContain("authoritative owner-native SQLite record; retained 30 days");
     expect(output).toContain("admission provenance only; no enforcement decision");
-    expect(output).toContain("evidence unavailable or corrupt; do not infer authorization");
     expect(output).not.toContain("named authoritative decision source");
-    expect(output).toContain("Policy refs: operator-approval:human-decision");
+    expect(output).toContain("Policy refs: 1");
+    expect(output).toContain("Policy refs: 0");
+    expect(output).toContain("Grant refs: 0");
     expect(output).toContain("Context used: contextId, executionId, runId");
+    expect(output).toContain("producer display contract unverified; receipt prose omitted");
+    for (const secret of hostileRawReceiptSecrets) {
+      expect(output).not.toContain(secret);
+    }
+    vi.mocked(runtime.log).mockClear();
+    await auditListCommand({ explain: true, runId: "run-1", json: true }, runtime);
+    const jsonOutput = vi.mocked(runtime.log).mock.calls.flat().join("\n");
+    expect(jsonOutput).toContain('"decisionDisplays"');
+    expect(jsonOutput).not.toContain('"decisions"');
+    for (const rawKey of ["receiptId", "resolutionRef", "eventId"]) {
+      expect(jsonOutput).not.toContain(`"${rawKey}"`);
+    }
+    for (const secret of hostileRawReceiptSecrets) {
+      expect(jsonOutput).not.toContain(secret);
+    }
   });
 
   it("renders ambiguous run discovery and selects an exact execution", async () => {
@@ -642,7 +644,7 @@ describe("audit run explanation", () => {
           },
         ],
       },
-      decisions: [],
+      decisionDisplays: [],
       coverage: { state: "unknown", missingEvidence: ["execution.selection"] },
     });
 
@@ -661,7 +663,7 @@ describe("audit run explanation", () => {
         missingEvidence: ["identity.context"],
         remediation: [{ code: "verify_execution_id", text: "Verify the exact execution id." }],
       },
-      decisions: [],
+      decisionDisplays: [],
       coverage: { state: "unknown", missingEvidence: ["identity.context"] },
     });
     await auditListCommand({ explain: true, executionId: "execution-2", json: true }, runtime);
@@ -681,7 +683,7 @@ describe("audit run explanation", () => {
         missingEvidence: ["identity.context"],
         remediation: [],
       },
-      decisions: [],
+      decisionDisplays: [],
       coverage: { state: "unknown", missingEvidence: ["identity.context"] },
     });
 
@@ -730,7 +732,7 @@ describe("audit run explanation", () => {
           },
         ],
       },
-      decisions: [],
+      decisionDisplays: [],
       coverage: { state: "unsupported", missingEvidence: ["identity.context"] },
     });
 
diff --git a/src/commands/audit.ts b/src/commands/audit.ts
index 3a35146cd5a7..93d32b81887c 100644
--- a/src/commands/audit.ts
+++ b/src/commands/audit.ts
@@ -11,7 +11,7 @@ import type {
   AuditListResult,
   AuditRunInspectParams,
   AuditRunInspectResult,
-  DecisionReceiptV1,
+  DecisionReceiptDisplayV1,
   ExecutionIdentityContextV1,
   PrincipalRefV1,
 } from "../../packages/gateway-protocol/src/index.js";
@@ -270,7 +270,7 @@ function unsupportedRunInspection(
         },
       ],
     },
-    decisions: [],
+    decisionDisplays: [],
     coverage: { state: "unsupported", missingEvidence },
   };
 }
@@ -399,32 +399,37 @@ function unavailableIdentityLines(state: "unknown" | "unsupported"): string[] {
   return IDENTITY_FIELD_LABELS.map((label) => fieldLine(label, state));
 }
 
-function decisionLines(receipt: DecisionReceiptV1): string[] {
+function decisionLines(receipt: DecisionReceiptDisplayV1): string[] {
   const evidence =
-    receipt.action.family === "run" && receipt.action.operation === "admission"
-      ? "admission provenance only; no enforcement decision"
-      : receipt.enforcement.coverageState === "unknown" ||
-          receipt.enforcement.coverageState === "unsupported"
-        ? "evidence unavailable or corrupt; do not infer authorization"
-        : receipt.source.owner === "operator_approvals"
-          ? "authoritative owner-native SQLite record; retained 30 days"
-          : receipt.enforcement.coverageState === "enforced"
-            ? "validated immutable decision fact; retained 30 days"
-            : "attribution record only; no enforcement decision";
+    receipt.provenance.state === "unverified"
+      ? "producer display contract unverified; receipt prose omitted"
+      : receipt.provenance.producer === "run-admission"
+        ? "admission provenance only; no enforcement decision"
+        : receipt.enforcement.coverageState === "unknown" ||
+            receipt.enforcement.coverageState === "unsupported"
+          ? "evidence unavailable or corrupt; do not infer authorization"
+          : receipt.provenance.producer === "operator-approval"
+            ? "authoritative owner-native SQLite record; retained 30 days"
+            : receipt.enforcement.coverageState === "enforced"
+              ? "validated immutable decision fact; retained 30 days"
+              : "attribution record only; no enforcement decision";
+  const producer =
+    receipt.provenance.state === "verified" ? receipt.provenance.producer : "unverified";
   return [
     `  ${safe(receipt.action.family)}.${safe(receipt.action.operation)}: ${safe(receipt.decision.outcome)}`,
     `    Coverage: ${safe(receipt.enforcement.coverageState)}`,
     `    Reason: ${safe(receipt.decision.reasonCode)}`,
-    `    Source: ${safe(receipt.source.owner)} at ${safe(receipt.source.decisionBoundary)}`,
+    `    Display producer: ${safe(producer)}`,
     `    Evidence: ${evidence}`,
-    `    Policy refs: ${receipt.enforcement.policyRefs.length > 0 ? receipt.enforcement.policyRefs.map(safe).join(", ") : "none"}`,
-    `    Grant refs: ${receipt.enforcement.grantRefs.length > 0 ? receipt.enforcement.grantRefs.map(safe).join(", ") : "none"}`,
+    `    Policy refs: ${receipt.enforcement.policyCount}`,
+    `    Grant refs: ${receipt.enforcement.grantCount}`,
     `    Context used: ${receipt.enforcement.contextFieldsUsed.length > 0 ? receipt.enforcement.contextFieldsUsed.map(safe).join(", ") : "none"}`,
     ...(receipt.action.summary ? [`    Summary: ${safe(receipt.action.summary)}`] : []),
   ];
 }
 
 function formatAuditRunInspection(result: AuditRunInspectResult): string[] {
+  const decisionDisplays = result.decisionDisplays;
   const selectorText = result.run.executionId
     ? `Execution ${safe(result.run.executionId)}${result.run.runId ? ` (run ${safe(result.run.runId)})` : ""}`
     : `Run ${safe(result.run.runId)}`;
@@ -473,10 +478,10 @@ function formatAuditRunInspection(result: AuditRunInspectResult): string[] {
     );
   }
   lines.push("", "Decisions");
-  if (result.decisions.length === 0) {
+  if (decisionDisplays.length === 0) {
     lines.push("  none [absent]");
   } else {
-    for (const receipt of result.decisions) {
+    for (const receipt of decisionDisplays) {
       lines.push(...decisionLines(receipt));
     }
   }
@@ -488,7 +493,7 @@ function formatAuditRunInspection(result: AuditRunInspectResult): string[] {
   );
   const remediation = [
     ...(result.identity.state === "present" ? [] : result.identity.remediation),
-    ...result.decisions.flatMap((decision) => decision.remediation),
+    ...decisionDisplays.flatMap((decision) => decision.remediation),
   ];
   lines.push("", "Next steps");
   lines.push(
diff --git a/src/gateway/operator-approval-receipts.test.ts b/src/gateway/operator-approval-receipts.test.ts
index f50a5abd4015..c55766c6cf57 100644
--- a/src/gateway/operator-approval-receipts.test.ts
+++ b/src/gateway/operator-approval-receipts.test.ts
@@ -1,5 +1,9 @@
 import { afterEach, describe, expect, it } from "vitest";
+import type { ExecutionIdentityContextV1 } from "../../packages/gateway-protocol/src/index.js";
+import { trackSqliteStatementExecutions } from "../../test/helpers/sqlite-statement-execution-counter.js";
 import { useAutoCleanupTempDirTracker } from "../../test/helpers/temp-dir.js";
+import { activityRunInspectorSearch } from "../../ui/src/pages/activity/run-inspector-model.js";
+import { presentExecutionDecisionReceipts } from "../audit/execution-decision-receipts.js";
 import { tableExists } from "../state/openclaw-state-db-schema-helpers.js";
 import {
   closeOpenClawStateDatabaseForTest,
@@ -79,6 +83,21 @@ const context = {
   createdAt: 500,
 };
 
+const identityContext: ExecutionIdentityContextV1 = {
+  schemaVersion: 1,
+  ...context,
+  trustDomain: { kind: "gateway-cell", domainRef: "domain-ref", state: "present" },
+  invoker: { state: "absent" },
+  ingress: { kind: "local-cli", boundary: "agent-command.local", state: "present" },
+  agentPrincipal: { kind: "agent", domainRef: "domain-ref", principalRef: "main" },
+  agentDefinition: { definitionRef: "main", state: "present" },
+  runtimeInstance: { runtimeRef: "runtime-ref", kind: "embedded", state: "present" },
+  applicableGrants: [],
+  assurance: [],
+  coverageState: "unattributed",
+  missingEvidence: [],
+};
+
 describe("operator approval decision receipts", () => {
   it("projects every terminal state from the authoritative first answer", () => {
     const database = databaseOptions();
@@ -150,12 +169,23 @@ describe("operator approval decision receipts", () => {
       .db.prepare("UPDATE operator_approvals SET presentation_json = ? WHERE approval_id = ?")
       .run("{", "payload-corrupt");
 
-    const receipts = pageOperatorApprovalReceiptsForRun({
+    const page = pageOperatorApprovalReceiptsForRun({
       context,
       limit: 20,
       nowMs: 3_000,
       databaseOptions: database,
-    }).receipts;
+    });
+    const receipts = page.entries.map((entry) => entry.receipt);
+    expect(page.entries.map((entry) => entry.selectorId)).toEqual([
+      "approval-decision:1",
+      "approval-decision:2",
+      "approval-decision:3",
+      "approval-decision:4",
+      "approval-decision:5",
+      "approval-decision:6",
+      "approval-decision:7",
+    ]);
+    expect(page.entries).toHaveLength(receipts.length);
     expect(
       summarizeOperatorApprovalReceiptsForRun({
         context,
@@ -204,6 +234,23 @@ describe("operator approval decision receipts", () => {
     ]) {
       expect(encoded).not.toContain(secret);
     }
+
+    const displays = presentExecutionDecisionReceipts({
+      context: identityContext,
+      decisionCursor: "a:0:0",
+      decisionLimit: 20,
+      options: { ...database, now: 3_000 },
+    }).decisionDisplays;
+    expect(displays?.[0]).toMatchObject({
+      action: {
+        family: "exec",
+        operation: "approval",
+        summary: "A exec approval allowed the requested action.",
+      },
+      provenance: { state: "verified", producer: "operator-approval" },
+      remediation: [],
+    });
+    expect(JSON.stringify(displays)).not.toContain("secret command");
   });
 
   it("keeps a denied first answer after a conflicting allow retry", () => {
@@ -233,7 +280,7 @@ describe("operator approval decision receipts", () => {
         limit: 10,
         nowMs: 2_001,
         databaseOptions: database,
-      }).receipts[0],
+      }).entries[0]?.receipt,
     ).toMatchObject({
       decision: { outcome: "denied", reasonCode: "operator_approval_denied_by_reviewer" },
       enforcement: {
@@ -295,8 +342,27 @@ describe("operator approval decision receipts", () => {
       nowMs: 3_000,
       databaseOptions: database,
     });
-    expect(first.receipts[0]?.receiptId).toContain("approval:");
+    expect(first.entries[0]?.receipt.receiptId).toContain("approval:");
     expect(first.nextCursor).toEqual({ occurredAt: 2_000, rowId: expect.any(Number) });
+    const firstDisplay = presentExecutionDecisionReceipts({
+      context: identityContext,
+      decisionCursor: "a:0:0",
+      decisionLimit: 1,
+      options: { ...database, now: 3_000 },
+    }).decisionDisplays[0];
+    expect(firstDisplay?.selectorId).toBe(`approval-decision:${first.nextCursor?.rowId}`);
+    expect(first.entries[0]?.selectorId).toBe(firstDisplay?.selectorId);
+    expect(firstDisplay?.selectorId).not.toBe(first.entries[0]?.receipt.receiptId);
+    const receiptSearch = activityRunInspectorSearch(
+      { kind: "run", id: context.runId },
+      { id: firstDisplay?.selectorId ?? "" },
+    );
+    expect(new URLSearchParams(receiptSearch.slice(1)).get("receipt")).toBe(
+      firstDisplay?.selectorId,
+    );
+    expect(receiptSearch).not.toContain(
+      encodeURIComponent(first.entries[0]?.receipt.receiptId ?? ""),
+    );
     expect(
       pageOperatorApprovalReceiptsForRun({
         context,
@@ -304,7 +370,7 @@ describe("operator approval decision receipts", () => {
         limit: 2,
         nowMs: 3_000,
         databaseOptions: database,
-      }).receipts,
+      }).entries.map((entry) => entry.receipt),
     ).toEqual([
       expect.objectContaining({
         decision: { outcome: "unknown", reasonCode: "operator_approval_payload_bounded" },
@@ -316,6 +382,84 @@ describe("operator approval decision receipts", () => {
     ]);
   });
 
+  it("projects each approval page from one owner snapshot without dropping outcomes", () => {
+    const database = databaseOptions();
+    for (const id of [
+      "snapshot-corrupt",
+      "snapshot-oversized",
+      "snapshot-unlinked",
+      "snapshot-valid",
+    ]) {
+      insertOperatorApproval({ approval: approval(id), databaseOptions: database });
+      resolveOperatorApproval({
+        id,
+        decision: "deny",
+        resolver: { kind: "device", id: "reviewer" },
+        nowMs: 2_000,
+        databaseOptions: database,
+      });
+    }
+    const db = openOpenClawStateDatabase(database).db;
+    db.prepare("UPDATE operator_approvals SET presentation_json = ? WHERE approval_id = ?").run(
+      "{",
+      "snapshot-corrupt",
+    );
+    db.prepare("UPDATE operator_approvals SET presentation_json = ? WHERE approval_id = ?").run(
+      JSON.stringify({ kind: "exec", commandText: "x".repeat(70_000) }),
+      "snapshot-oversized",
+    );
+    db.prepare("DELETE FROM operator_approval_execution_identities WHERE approval_id = ?").run(
+      "snapshot-unlinked",
+    );
+    const expectedSelectors = new Map(
+      (
+        db
+          .prepare(
+            "SELECT approval_id, rowid AS receipt_rowid FROM operator_approvals WHERE source_run_id = ?",
+          )
+          .all(context.runId) as Array<{ approval_id: string; receipt_rowid: number }>
+      ).map((row) => [row.approval_id, `approval-decision:${row.receipt_rowid}`]),
+    );
+    const tracker = trackSqliteStatementExecutions(db, ["approvalPage"] as const, (sqlText) =>
+      sqlText.trimStart().toLowerCase().startsWith("select") &&
+      sqlText.includes("operator_approvals")
+        ? "approvalPage"
+        : null,
+    );
+
+    try {
+      const first = pageOperatorApprovalReceiptsForRun({
+        context,
+        limit: 2,
+        nowMs: 3_000,
+        databaseOptions: database,
+      });
+      const second = pageOperatorApprovalReceiptsForRun({
+        context,
+        after: first.nextCursor,
+        limit: 10,
+        nowMs: 3_000,
+        databaseOptions: database,
+      });
+      const entries = [...first.entries, ...second.entries];
+      expect(tracker.counts.approvalPage).toBe(2);
+      expect(entries).toHaveLength(4);
+      expect(entries.map((entry) => entry.receipt.decision.reasonCode)).toEqual([
+        "operator_approval_record_corrupt",
+        "operator_approval_payload_bounded",
+        "operator_approval_execution_link_missing",
+        "operator_approval_denied_by_reviewer",
+      ]);
+      expect(entries.map((entry) => entry.selectorId)).toEqual(
+        ["snapshot-corrupt", "snapshot-oversized", "snapshot-unlinked", "snapshot-valid"].map(
+          (id) => expectedSelectors.get(id),
+        ),
+      );
+    } finally {
+      tracker.restore();
+    }
+  });
+
   it("never enforces a later unrelated approval that reuses the retained run id", () => {
     const database = databaseOptions();
     insertOperatorApproval({ approval: approval("retained"), databaseOptions: database });
@@ -346,7 +490,7 @@ describe("operator approval decision receipts", () => {
         limit: 10,
         nowMs: 4_000,
         databaseOptions: database,
-      }).receipts.map((receipt) => receipt.enforcement.coverageState),
+      }).entries.map((entry) => entry.receipt.enforcement.coverageState),
     ).toEqual(["enforced", "unknown"]);
   });
 
@@ -388,7 +532,7 @@ describe("operator approval decision receipts", () => {
           limit: 10,
           nowMs: 4_000,
           databaseOptions: database,
-        }).receipts,
+        }).entries.map((entry) => entry.receipt),
       ).toEqual([
         expect.objectContaining({
           decision: { outcome: "unknown", reasonCode },
@@ -419,7 +563,7 @@ describe("operator approval decision receipts", () => {
         limit: 10,
         nowMs: RETENTION_MS + 2,
         databaseOptions: database,
-      }).receipts,
+      }).entries.map((entry) => entry.receipt),
     ).toEqual([]);
     expect(tableExists(openOpenClawStateDatabase(database).db, "execution_decision_facts")).toBe(
       false,
diff --git a/src/gateway/operator-approval-store.ts b/src/gateway/operator-approval-store.ts
index 62d452038ac0..174d94553ea2 100644
--- a/src/gateway/operator-approval-store.ts
+++ b/src/gateway/operator-approval-store.ts
@@ -21,6 +21,7 @@ import {
   executeSqliteQueryTakeFirstSync,
   getNodeSqliteKysely,
 } from "../infra/kysely-sync.js";
+import { normalizeSqliteNumber } from "../infra/sqlite-number.js";
 import { withExistingOpenClawStateDatabaseReadOnly } from "../state/openclaw-state-db-readonly.js";
 import { tableExists } from "../state/openclaw-state-db-schema-helpers.js";
 import type {
@@ -186,17 +187,26 @@ type OperatorApprovalReceiptRow = OperatorApprovalRow & {
   binding_execution_id: string | null;
 };
 type OperatorApprovalReceiptCursor = { occurredAt: number; rowId: number };
-type OperatorApprovalReceiptMetadataRow = Pick<
-  OperatorApprovalRow,
-  "approval_id" | "kind" | "resolution_ref" | "resolved_at_ms" | "updated_at_ms"
+type OperatorApprovalReceiptSnapshotRow = Omit<
+  OperatorApprovalReceiptRow,
+  "presentation_json" | "reviewer_device_ids_json" | "audience_session_keys_json"
 > & {
-  binding_context_id: string | null;
-  binding_execution_id: string | null;
+  presentation_json: string | null;
+  reviewer_device_ids_json: string | null;
+  audience_session_keys_json: string | null;
   receipt_rowid: number;
   payload_bytes: number;
 };
+type OperatorApprovalReceiptSnapshotQueryRow = OperatorApprovalReceiptSnapshotRow & {
+  cursor_boundary_rowid: number | null;
+  page_present: 0 | 1;
+};
+type OperatorApprovalReceiptPageEntry = {
+  receipt: DecisionReceiptV1;
+  selectorId: string;
+};
 type OperatorApprovalReceiptPage = {
-  receipts: DecisionReceiptV1[];
+  entries: OperatorApprovalReceiptPageEntry[];
   nextCursor?: OperatorApprovalReceiptCursor;
 };
 type OperatorApprovalExecutionLinkState = "exact" | "missing" | "malformed" | "mismatch";
@@ -747,7 +757,7 @@ function projectCorruptOperatorApprovalReceipt(
 }
 
 function projectOversizedOperatorApprovalReceipt(
-  row: OperatorApprovalReceiptMetadataRow,
+  row: OperatorApprovalReceiptSnapshotRow,
   context: OperatorApprovalReceiptContext,
 ): DecisionReceiptV1 {
   const receipt = projectCorruptOperatorApprovalReceipt(row, context);
@@ -781,6 +791,16 @@ function operatorApprovalRowId() {
   return /* kysely-allow-raw: SQLite rowid keeps the external cursor compact while the indexed approval id remains the query key. */ sql<number>`operator_approvals.rowid`;
 }
 
+function operatorApprovalSelectorId(
+  row: Pick<OperatorApprovalReceiptSnapshotRow, "receipt_rowid">,
+): string {
+  const rowId = normalizeSqliteNumber(row.receipt_rowid);
+  if (rowId === undefined || rowId < 1) {
+    throw new Error("invalid operator approval receipt rowid");
+  }
+  return `approval-decision:${rowId}`;
+}
+
 function operatorApprovalPayloadBytes() {
   return /* kysely-allow-raw: SQLite byte length excludes oversized retained presentation JSON before materialization. */ sql<number>`
     length(CAST(operator_approvals.presentation_json AS BLOB)) +
@@ -789,121 +809,165 @@ function operatorApprovalPayloadBytes() {
   `;
 }
 
-function terminalApprovalReceiptMetadataRows(params: {
+const OPERATOR_APPROVAL_PAYLOAD_COLUMNS = {
+  presentation_json: sql`operator_approvals.presentation_json`,
+  reviewer_device_ids_json: sql`operator_approvals.reviewer_device_ids_json`,
+  audience_session_keys_json: sql`operator_approvals.audience_session_keys_json`,
+} as const;
+
+function boundedOperatorApprovalPayload(column: keyof typeof OPERATOR_APPROVAL_PAYLOAD_COLUMNS) {
+  return /* kysely-allow-raw: the page statement must not materialize owner payload JSON above its audit bound. */ sql<
+    string | null
+  >`CASE WHEN ${operatorApprovalPayloadBytes()} <= ${OPERATOR_APPROVAL_RECEIPT_MAX_PAYLOAD_BYTES} THEN ${OPERATOR_APPROVAL_PAYLOAD_COLUMNS[column]} ELSE NULL END`;
+}
+
+function operatorApprovalReceiptSnapshotColumns(hasExecutionIdentityTable: boolean) {
+  const bindingContextId = hasExecutionIdentityTable
+    ? sql`operator_approval_execution_identities.source_context_id`
+    : sql`NULL`;
+  const bindingExecutionId = hasExecutionIdentityTable
+    ? sql`operator_approval_execution_identities.source_execution_id`
+    : sql`NULL`;
+  return sql`
+    operator_approvals.approval_id,
+    operator_approvals.consumed_at_ms,
+    operator_approvals.consumed_by,
+    operator_approvals.created_at_ms,
+    operator_approvals.decision,
+    operator_approvals.expires_at_ms,
+    operator_approvals.kind,
+    ${boundedOperatorApprovalPayload("presentation_json")} AS presentation_json,
+    operator_approvals.requested_by_client_id,
+    operator_approvals.requested_by_device_id,
+    operator_approvals.requested_by_device_token_auth,
+    operator_approvals.resolution_ref,
+    operator_approvals.resolved_at_ms,
+    operator_approvals.resolver_id,
+    operator_approvals.resolver_kind,
+    ${boundedOperatorApprovalPayload("reviewer_device_ids_json")} AS reviewer_device_ids_json,
+    operator_approvals.runtime_epoch,
+    operator_approvals.source_agent_id,
+    operator_approvals.source_run_id,
+    operator_approvals.source_session_id,
+    operator_approvals.source_session_key,
+    operator_approvals.source_tool_call_id,
+    operator_approvals.source_tool_name,
+    operator_approvals.status,
+    operator_approvals.terminal_reason,
+    operator_approvals.updated_at_ms,
+    ${boundedOperatorApprovalPayload("audience_session_keys_json")} AS audience_session_keys_json,
+    ${bindingContextId} AS binding_context_id,
+    ${bindingExecutionId} AS binding_execution_id,
+    ${operatorApprovalRowId()} AS receipt_rowid,
+    ${operatorApprovalPayloadBytes()} AS payload_bytes
+  `;
+}
+
+function terminalApprovalReceiptPageRows(params: {
   db: DatabaseSync;
-  stateDb: ReturnType<typeof getNodeSqliteKysely<OperatorApprovalDatabase>>;
   runId: string;
   nowMs: number;
   after?: OperatorApprovalReceiptCursor;
   offset?: number;
   limit: number;
-}): OperatorApprovalReceiptMetadataRow[] {
-  const boundary = params.after
-    ? executeSqliteQueryTakeFirstSync(
-        params.db,
-        params.stateDb
-          .selectFrom("operator_approvals")
-          .select(["approval_id", "resolved_at_ms"])
-          .where(operatorApprovalRowId(), "=", params.after.rowId)
-          .where("source_run_id", "=", params.runId)
-          .where("resolved_at_ms", "=", params.after.occurredAt),
-      )
-    : undefined;
-  if (params.after && !boundary) {
-    throw new Error("operator approval decision cursor is no longer retained");
-  }
-  const ordered = terminalApprovalsForRunQuery(params.stateDb, params.runId, params.nowMs)
-    .$if(boundary !== undefined && boundary.resolved_at_ms !== null, (query) =>
-      query.where((eb) =>
-        eb.or([
-          eb("operator_approvals.resolved_at_ms", ">", boundary!.resolved_at_ms!),
-          eb.and([
-            eb("operator_approvals.resolved_at_ms", "=", boundary!.resolved_at_ms!),
-            eb("operator_approvals.approval_id", ">", boundary!.approval_id),
-          ]),
-        ]),
-      ),
-    )
-    .orderBy("operator_approvals.resolved_at_ms", "asc")
-    .orderBy("operator_approvals.approval_id", "asc")
-    .$if(params.offset !== undefined, (query) => query.offset(params.offset!))
-    .limit(params.limit);
-  const metadata = (query: typeof ordered) =>
-    query
-      .select([
-        "operator_approvals.approval_id",
-        "operator_approvals.kind",
-        "operator_approvals.resolution_ref",
-        "operator_approvals.resolved_at_ms",
-        "operator_approvals.updated_at_ms",
-      ])
-      .select([
-        operatorApprovalRowId().as("receipt_rowid"),
-        operatorApprovalPayloadBytes().as("payload_bytes"),
-      ]);
-  if (!tableExists(params.db, "operator_approval_execution_identities")) {
-    return executeSqliteQuerySync(
-      params.db,
-      metadata(ordered).select((eb) => [
-        eb.val(null).as("binding_context_id"),
-        eb.val(null).as("binding_execution_id"),
-      ]),
-    ).rows;
-  }
-  return executeSqliteQuerySync(
+}): OperatorApprovalReceiptSnapshotRow[] {
+  const hasExecutionIdentityTable = tableExists(
     params.db,
-    metadata(ordered)
-      .leftJoin(
-        "operator_approval_execution_identities",
-        "operator_approval_execution_identities.approval_id",
-        "operator_approvals.approval_id",
-      )
-      .select([
-        "operator_approval_execution_identities.source_context_id as binding_context_id",
-        "operator_approval_execution_identities.source_execution_id as binding_execution_id",
-      ]),
-  ).rows;
-}
-
-function terminalApprovalReceiptRowsById(params: {
-  db: DatabaseSync;
-  stateDb: ReturnType<typeof getNodeSqliteKysely<OperatorApprovalDatabase>>;
-  ids: readonly string[];
-}): Map<string, OperatorApprovalReceiptRow> {
-  if (params.ids.length === 0) {
-    return new Map();
-  }
-  const query = params.stateDb
-    .selectFrom("operator_approvals")
-    .where("operator_approvals.approval_id", "in", [...params.ids])
-    .where(operatorApprovalPayloadBytes(), "<=", OPERATOR_APPROVAL_RECEIPT_MAX_PAYLOAD_BYTES);
-  if (!tableExists(params.db, "operator_approval_execution_identities")) {
-    const rows = executeSqliteQuerySync(
-      params.db,
-      query
-        .selectAll("operator_approvals")
-        .select((eb) => [
-          eb.val(null).as("binding_context_id"),
-          eb.val(null).as("binding_execution_id"),
-        ]),
-    ).rows;
-    return new Map(rows.map((row) => [row.approval_id, row]));
-  }
+    "operator_approval_execution_identities",
+  );
+  const executionIdentityJoin = hasExecutionIdentityTable
+    ? sql`LEFT JOIN operator_approval_execution_identities
+          ON operator_approval_execution_identities.approval_id = operator_approvals.approval_id`
+    : sql``;
+  const cutoffMs = params.nowMs - OPERATOR_APPROVAL_TERMINAL_RETENTION_MS;
+  const offset = params.offset ?? 0;
+  const pageStatement = params.after
+    ? /* kysely-allow-raw: one CTE statement preserves cursor validation and pairs each owner rowid with its bounded receipt payload in the same SQLite snapshot. */ sql<OperatorApprovalReceiptSnapshotQueryRow>`
+        WITH cursor_boundary AS (
+          SELECT approval_id, resolved_at_ms, ${operatorApprovalRowId()} AS receipt_rowid
+          FROM operator_approvals
+          WHERE ${operatorApprovalRowId()} = ${params.after.rowId}
+            AND source_run_id = ${params.runId}
+            AND resolved_at_ms = ${params.after.occurredAt}
+        ), approval_page AS (
+          SELECT ${operatorApprovalReceiptSnapshotColumns(hasExecutionIdentityTable)}
+          FROM operator_approvals
+          ${executionIdentityJoin}
+          CROSS JOIN cursor_boundary
+          WHERE operator_approvals.source_run_id = ${params.runId}
+            AND operator_approvals.status != 'pending'
+            AND operator_approvals.resolved_at_ms IS NOT NULL
+            AND operator_approvals.resolved_at_ms >= ${cutoffMs}
+            AND (
+              operator_approvals.resolved_at_ms > cursor_boundary.resolved_at_ms
+              OR (
+                operator_approvals.resolved_at_ms = cursor_boundary.resolved_at_ms
+                AND operator_approvals.approval_id > cursor_boundary.approval_id
+              )
+            )
+          ORDER BY operator_approvals.resolved_at_ms ASC, operator_approvals.approval_id ASC
+          LIMIT ${params.limit} OFFSET ${offset}
+        )
+        SELECT
+          cursor_boundary.receipt_rowid AS cursor_boundary_rowid,
+          CASE WHEN approval_page.receipt_rowid IS NULL THEN 0 ELSE 1 END AS page_present,
+          approval_page.*
+        FROM (SELECT 1) AS snapshot_seed
+        LEFT JOIN cursor_boundary ON TRUE
+        LEFT JOIN approval_page ON TRUE
+        ORDER BY approval_page.resolved_at_ms ASC, approval_page.approval_id ASC
+      `
+    : /* kysely-allow-raw: the initial page returns owner rowids and bounded receipt payloads in one SQLite snapshot. */ sql<OperatorApprovalReceiptSnapshotQueryRow>`
+        SELECT
+          NULL AS cursor_boundary_rowid,
+          1 AS page_present,
+          ${operatorApprovalReceiptSnapshotColumns(hasExecutionIdentityTable)}
+        FROM operator_approvals
+        ${executionIdentityJoin}
+        WHERE operator_approvals.source_run_id = ${params.runId}
+          AND operator_approvals.status != 'pending'
+          AND operator_approvals.resolved_at_ms IS NOT NULL
+          AND operator_approvals.resolved_at_ms >= ${cutoffMs}
+        ORDER BY operator_approvals.resolved_at_ms ASC, operator_approvals.approval_id ASC
+        LIMIT ${params.limit} OFFSET ${offset}
+      `;
+  const stateDb = getNodeSqliteKysely<OperatorApprovalDatabase>(params.db);
   const rows = executeSqliteQuerySync(
     params.db,
-    query
-      .leftJoin(
-        "operator_approval_execution_identities",
-        "operator_approval_execution_identities.approval_id",
-        "operator_approvals.approval_id",
+    stateDb
+      .selectFrom(
+        /* kysely-allow-raw: this derived table preserves the single owner-snapshot statement while exposing its closed row shape to Kysely. */
+        sql<OperatorApprovalReceiptSnapshotQueryRow>`(${pageStatement})`.as("approval_snapshot"),
       )
-      .selectAll("operator_approvals")
-      .select([
-        "operator_approval_execution_identities.source_context_id as binding_context_id",
-        "operator_approval_execution_identities.source_execution_id as binding_execution_id",
-      ]),
+      .selectAll(),
   ).rows;
-  return new Map(rows.map((row) => [row.approval_id, row]));
+  if (params.after && rows[0]?.cursor_boundary_rowid === null) {
+    throw new Error("operator approval decision cursor is no longer retained");
+  }
+  if (rows.length === 1 && rows[0]?.page_present === 0) {
+    return [];
+  }
+  return rows.map((row) => {
+    if (row.page_present !== 1) {
+      throw new Error("operator approval page snapshot is malformed");
+    }
+    return row;
+  });
+}
+
+function materializeBoundedOperatorApprovalRow(
+  row: OperatorApprovalReceiptSnapshotRow,
+): OperatorApprovalReceiptRow | null {
+  return typeof row.presentation_json === "string" &&
+    typeof row.reviewer_device_ids_json === "string" &&
+    typeof row.audience_session_keys_json === "string"
+    ? {
+        ...row,
+        presentation_json: row.presentation_json,
+        reviewer_device_ids_json: row.reviewer_device_ids_json,
+        audience_session_keys_json: row.audience_session_keys_json,
+      }
+    : null;
 }
 
 function operatorApprovalExecutionLinkState(
@@ -977,14 +1041,13 @@ export function summarizeOperatorApprovalReceiptsForRun(params: {
         return { count: 0, missingEvidence: [] };
       }
       const stateDb = getNodeSqliteKysely<OperatorApprovalDatabase>(db);
-      const metadataRows = terminalApprovalReceiptMetadataRows({
+      const snapshotRows = terminalApprovalReceiptPageRows({
         db,
-        stateDb,
         runId: params.context.runId,
         nowMs: params.nowMs ?? Date.now(),
         limit: OPERATOR_APPROVAL_RECEIPT_SUMMARY_MAX_ROWS + 1,
       });
-      const boundedCount = metadataRows.length;
+      const boundedCount = snapshotRows.length;
       const count = params.exactCount
         ? (executeSqliteQueryTakeFirstSync(
             db,
@@ -1005,26 +1068,19 @@ export function summarizeOperatorApprovalReceiptsForRun(params: {
           missingEvidence: ["operator_approval.summary_bounded"],
         };
       }
-      const hasOversizedRecord = metadataRows.some(
+      const hasOversizedRecord = snapshotRows.some(
         (row) => row.payload_bytes > OPERATOR_APPROVAL_RECEIPT_MAX_PAYLOAD_BYTES,
       );
-      const boundedMetadataRows = metadataRows.filter(
+      const boundedSnapshotRows = snapshotRows.filter(
         (row) => row.payload_bytes <= OPERATOR_APPROVAL_RECEIPT_MAX_PAYLOAD_BYTES,
       );
-      const rowsById = terminalApprovalReceiptRowsById({
-        db,
-        stateDb,
-        ids: boundedMetadataRows.map((row) => row.approval_id),
-      });
-      const rows = metadataRows.flatMap((metadata) => {
-        const row = rowsById.get(metadata.approval_id);
-        return row ? [row] : [];
-      });
-      const hasMissingBoundedRow = rows.length !== boundedMetadataRows.length;
-      const records = rows.map((row) => decodeOperatorApprovalRow(row));
+      const rows = boundedSnapshotRows.map(materializeBoundedOperatorApprovalRow);
+      const hasMissingBoundedRow = rows.some((row) => row === null);
+      const records = rows.map((row) => (row === null ? null : decodeOperatorApprovalRow(row)));
       const hasCorruptRecord = records.some((record) => record === null);
       const hasUnlinkedRecord = rows.some(
         (row, index) =>
+          row !== null &&
           records[index] !== null &&
           operatorApprovalExecutionLinkState(row, params.context) !== "exact",
       );
@@ -1058,47 +1114,40 @@ export function pageOperatorApprovalReceiptsForRun(params: {
   return (
     withExistingOpenClawStateDatabaseReadOnly(({ db }) => {
       if (!tableExists(db, "operator_approvals")) {
-        return { receipts: [] };
+        return { entries: [] };
       }
-      const stateDb = getNodeSqliteKysely<OperatorApprovalDatabase>(db);
-      const metadataRows = terminalApprovalReceiptMetadataRows({
+      const snapshotRows = terminalApprovalReceiptPageRows({
         db,
-        stateDb,
         runId: params.context.runId,
         nowMs: params.nowMs ?? Date.now(),
         after: params.after,
         offset: params.offset,
         limit: params.limit + 1,
       });
-      const pageMetadata = metadataRows.slice(0, params.limit);
-      const rowsById = terminalApprovalReceiptRowsById({
-        db,
-        stateDb,
-        ids: pageMetadata
-          .filter((row) => row.payload_bytes <= OPERATOR_APPROVAL_RECEIPT_MAX_PAYLOAD_BYTES)
-          .map((row) => row.approval_id),
+      const pageRows = snapshotRows.slice(0, params.limit);
+      const entries = pageRows.map((snapshot) => {
+        let receipt: DecisionReceiptV1;
+        if (snapshot.payload_bytes > OPERATOR_APPROVAL_RECEIPT_MAX_PAYLOAD_BYTES) {
+          receipt = projectOversizedOperatorApprovalReceipt(snapshot, params.context);
+        } else {
+          const row = materializeBoundedOperatorApprovalRow(snapshot);
+          const record = row === null ? null : decodeOperatorApprovalRow(row);
+          if (row === null || record === null) {
+            receipt = projectCorruptOperatorApprovalReceipt(snapshot, params.context);
+          } else {
+            const linkState = operatorApprovalExecutionLinkState(row, params.context);
+            receipt =
+              linkState === "exact"
+                ? projectOperatorApprovalReceipt(record, params.context)
+                : projectUnlinkedOperatorApprovalReceipt(record, params.context, linkState);
+          }
+        }
+        return { receipt, selectorId: operatorApprovalSelectorId(snapshot) };
       });
-      const receipts = pageMetadata.map((metadata) => {
-        if (metadata.payload_bytes > OPERATOR_APPROVAL_RECEIPT_MAX_PAYLOAD_BYTES) {
-          return projectOversizedOperatorApprovalReceipt(metadata, params.context);
-        }
-        const row = rowsById.get(metadata.approval_id);
-        if (!row) {
-          return projectCorruptOperatorApprovalReceipt(metadata, params.context);
-        }
-        const record = decodeOperatorApprovalRow(row);
-        if (!record) {
-          return projectCorruptOperatorApprovalReceipt(row, params.context);
-        }
-        const linkState = operatorApprovalExecutionLinkState(row, params.context);
-        return linkState === "exact"
-          ? projectOperatorApprovalReceipt(record, params.context)
-          : projectUnlinkedOperatorApprovalReceipt(record, params.context, linkState);
-      });
-      const last = pageMetadata.at(-1);
+      const last = pageRows.at(-1);
       return {
-        receipts,
-        ...(metadataRows.length > params.limit && last && last.resolved_at_ms !== null
+        entries,
+        ...(snapshotRows.length > params.limit && last && last.resolved_at_ms !== null
           ? {
               nextCursor: {
                 occurredAt: last.resolved_at_ms,
@@ -1107,7 +1156,7 @@ export function pageOperatorApprovalReceiptsForRun(params: {
             }
           : {}),
       };
-    }, params.databaseOptions) ?? { receipts: [] }
+    }, params.databaseOptions) ?? { entries: [] }
   );
 }
 
diff --git a/src/gateway/server-methods/audit.test.ts b/src/gateway/server-methods/audit.test.ts
index 1975e04e912e..81eed6370df5 100644
--- a/src/gateway/server-methods/audit.test.ts
+++ b/src/gateway/server-methods/audit.test.ts
@@ -59,6 +59,7 @@ describe("audit gateway methods", () => {
         remediation: [{ code: "verify_run_id", text: "Verify the exact run id." }],
       },
       decisions: [],
+      decisionDisplays: [],
       coverage: { state: "unknown", missingEvidence: ["run.record"] },
     });
   });
@@ -353,6 +354,155 @@ describe("audit gateway methods", () => {
     });
   });
 
+  it("serializes only the safe decision projection", async () => {
+    const hostile = {
+      receipt: "U2_R6_GATEWAY_RECEIPT_SECRET_05d8",
+      resolutionRef: "U2_R6_GATEWAY_RESOLUTION_REF_SECRET_a941",
+      eventId: "U2_R6_GATEWAY_EVENT_ID_SECRET_7b21",
+      context: "U2_R6_GATEWAY_CONTEXT_SECRET_812a",
+      execution: "U2_R6_GATEWAY_EXECUTION_SECRET_469b",
+      run: "U2_R6_GATEWAY_RUN_SECRET_e8e7",
+      resource: "U2_R6_GATEWAY_RESOURCE_SECRET_170c",
+      target: "U2_R6_GATEWAY_TARGET_SECRET_1d49",
+      record: "U2_R6_GATEWAY_RECORD_SECRET_017b",
+      evaluator: "U2_R6_GATEWAY_EVALUATOR_SECRET_2aa3",
+      owner: "U2_R6_GATEWAY_OWNER_SECRET_f72d",
+      policy: "U2_R6_GATEWAY_POLICY_SECRET_7ae1",
+      grant: "U2_R6_GATEWAY_GRANT_SECRET_8da2",
+      reason: "U2_R6_GATEWAY_REASON_SECRET_bf5f",
+      remediationCode: "U2_R6_GATEWAY_REMEDIATION_CODE_SECRET_96c3",
+      remediationText: "U2_R6_GATEWAY_REMEDIATION_TEXT_SECRET_e403",
+      generic:
+        "U2_R6_GATEWAY_COMMAND_PATH_TOOL_INPUT_PERMISSION_TITLE_INPUT_METADATA_GENERIC_SECRET_66a1",
+    };
+    inspectExecutionIdentityRun.mockReturnValueOnce({
+      schemaVersion: 1,
+      run: { runId: "run-1", executionId: "execution-1", status: "known" },
+      identity: {
+        state: "unknown",
+        reasonCode: "run_not_found",
+        missingEvidence: ["run.record"],
+        remediation: [],
+      },
+      decisions: [
+        {
+          schemaVersion: 1,
+          receiptId: hostile.receipt,
+          contextId: hostile.context,
+          executionId: hostile.execution,
+          runId: hostile.run,
+          actionId: hostile.eventId,
+          occurredAt: 1,
+          action: {
+            family: "tool",
+            operation: "execute",
+            resourceRef: hostile.resource,
+            targetRef: hostile.target,
+            summary: hostile.generic,
+          },
+          decision: { outcome: "allowed", reasonCode: hostile.reason },
+          enforcement: {
+            coverageState: "enforced",
+            evaluatorRef: hostile.evaluator,
+            policyRefs: [hostile.policy],
+            grantRefs: [hostile.grant],
+            contextFieldsUsed: [],
+          },
+          source: {
+            owner: hostile.owner,
+            recordRef: hostile.resolutionRef,
+            decisionBoundary: hostile.record,
+          },
+          missingEvidence: [],
+          remediation: [{ code: hostile.remediationCode, text: hostile.remediationText }],
+        },
+      ],
+      decisionDisplays: [],
+      coverage: { state: "unknown", missingEvidence: ["run.record"] },
+    });
+
+    const respond = await runAuditHandler("audit.run.inspect", { executionId: "execution-1" });
+    const result = respond.mock.calls[0]?.[1];
+    const json = JSON.stringify(result);
+
+    expect(result).not.toHaveProperty("decisions");
+    expect(result).toEqual(
+      expect.objectContaining({ decisionDisplays: [], coverage: expect.any(Object) }),
+    );
+    for (const rawKey of ["receiptId", "resolutionRef", "eventId"]) {
+      expect(json).not.toContain(`"${rawKey}"`);
+    }
+    for (const secret of Object.values(hostile)) {
+      expect(json).not.toContain(secret);
+    }
+  });
+
+  it.each([
+    {
+      name: "present",
+      identity: {
+        state: "present",
+        context: {
+          schemaVersion: 1,
+          contextId: "context-1",
+          executionId: "execution-1",
+          runId: "run-1",
+          createdAt: 1,
+          trustDomain: { kind: "gateway-cell", domainRef: accountRef, state: "present" },
+          invoker: { state: "absent" },
+          ingress: {
+            kind: "gateway-client",
+            boundary: "gateway.ws.authenticated-connect",
+            state: "present",
+          },
+          agentPrincipal: { kind: "agent", domainRef: accountRef, principalRef: "main" },
+          agentDefinition: { definitionRef: "main", state: "present" },
+          runtimeInstance: { runtimeRef: accountRef, kind: "gateway", state: "present" },
+          applicableGrants: [],
+          assurance: [],
+          coverageState: "unattributed",
+          missingEvidence: [],
+        },
+      },
+    },
+    {
+      name: "unavailable",
+      identity: {
+        state: "unsupported",
+        reasonCode: "identity_context_unavailable",
+        missingEvidence: ["identity.context"],
+        remediation: [],
+      },
+    },
+    {
+      name: "ambiguous",
+      identity: {
+        state: "ambiguous",
+        reasonCode: "execution_selection_required",
+        candidates: [],
+        missingEvidence: ["execution.selection"],
+        remediation: [],
+      },
+    },
+  ] as const)("keeps the $name success response safe-only", async ({ identity }) => {
+    inspectExecutionIdentityRun.mockReturnValueOnce({
+      schemaVersion: 1,
+      run: { runId: "run-1", status: "known" },
+      identity,
+      decisions: [],
+      decisionDisplays: [],
+      coverage: { state: "unknown", missingEvidence: [] },
+    });
+
+    const respond = await runAuditHandler("audit.run.inspect", { runId: "run-1" });
+    const result = respond.mock.calls[0]?.[1];
+    expect(result).toEqual(
+      expect.objectContaining({ decisionDisplays: [], coverage: expect.any(Object) }),
+    );
+    expect(result).not.toHaveProperty("decisions");
+    expect(JSON.stringify(result)).not.toContain('"decisions"');
+  });
+
   it("rejects malformed run inspection before storage access", async () => {
     expect(
       await runAuditHandler("audit.run.inspect", { runId: "", extra: true }),
diff --git a/src/gateway/server-methods/audit.ts b/src/gateway/server-methods/audit.ts
index b4a645f9b86d..36065cd56cad 100644
--- a/src/gateway/server-methods/audit.ts
+++ b/src/gateway/server-methods/audit.ts
@@ -5,6 +5,7 @@ import {
   errorShape,
   type AuditActivityEventV1,
   type AuditEvent,
+  type AuditRunInspectResult,
   validateAuditActivityListParams,
   validateAuditListParams,
   validateAuditRunInspectParams,
@@ -20,6 +21,7 @@ import type {
 import {
   ExecutionDecisionCursorError,
   isExecutionDecisionCursor,
+  type InternalAuditRunInspectResult,
 } from "../../audit/execution-decision-receipts.js";
 import { inspectExecutionIdentityRun } from "../../audit/execution-identity-context.js";
 import type { GatewayRequestHandlers } from "./types.js";
@@ -28,6 +30,25 @@ import { assertValidParams } from "./validation.js";
 const DEFAULT_AUDIT_LIST_LIMIT = 100;
 const MAX_AUDIT_LIST_LIMIT = 500;
 
+function serializeAuditRunInspectResult(
+  inspected: InternalAuditRunInspectResult,
+): AuditRunInspectResult {
+  const result: AuditRunInspectResult = {
+    schemaVersion: inspected.schemaVersion,
+    run: inspected.run,
+    identity: inspected.identity,
+    decisionDisplays: inspected.decisionDisplays,
+    coverage: inspected.coverage,
+  };
+  if (inspected.nextDecisionCursor !== undefined) {
+    result.nextDecisionCursor = inspected.nextDecisionCursor;
+  }
+  if (inspected.nextExecutionCursor !== undefined) {
+    result.nextExecutionCursor = inspected.nextExecutionCursor;
+  }
+  return result;
+}
+
 /** Preserve the shipped audit.list result shape for run/tool-only clients. */
 function mapLegacyAuditEvent(
   event: AgentRunAuditEventRecord | ToolActionAuditEventRecord,
@@ -196,17 +217,19 @@ export const auditHandlers: GatewayRequestHandlers = {
     try {
       respond(
         true,
-        inspectExecutionIdentityRun({
-          ...(typeof params.runId === "string"
-            ? {
-                runId: params.runId,
-                ...(executionOffset !== undefined ? { executionOffset } : {}),
-                executionLimit: params.executionLimit ?? 50,
-              }
-            : { executionId: params.executionId! }),
-          ...(decisionCursor !== undefined ? { decisionCursor } : {}),
-          decisionLimit: params.decisionLimit ?? 50,
-        }),
+        serializeAuditRunInspectResult(
+          inspectExecutionIdentityRun({
+            ...(typeof params.runId === "string"
+              ? {
+                  runId: params.runId,
+                  ...(executionOffset !== undefined ? { executionOffset } : {}),
+                  executionLimit: params.executionLimit ?? 50,
+                }
+              : { executionId: params.executionId! }),
+            ...(decisionCursor !== undefined ? { decisionCursor } : {}),
+            decisionLimit: params.decisionLimit ?? 50,
+          }),
+        ),
       );
     } catch (error) {
       if (error instanceof ExecutionDecisionCursorError) {
diff --git a/test/e2e/qa-lab/runtime/agent-run-decision-receipt.ts b/test/e2e/qa-lab/runtime/agent-run-decision-receipt.ts
index c3307bcf38bb..0e2930d3d648 100644
--- a/test/e2e/qa-lab/runtime/agent-run-decision-receipt.ts
+++ b/test/e2e/qa-lab/runtime/agent-run-decision-receipt.ts
@@ -46,11 +46,11 @@ function parseOptions(argv: readonly string[]): ProducerOptions {
   };
 }
 
-function parseJson<T>(raw: string, label: string): T {
+function parseJson(raw: string, label: string): AuditRunInspectResult {
   try {
-    return JSON.parse(raw) as T;
+    return JSON.parse(raw) as AuditRunInspectResult;
   } catch (error) {
-    throw new Error(`${label} was not JSON: ${formatErrorMessage(error)}`);
+    throw new Error(`${label} was not JSON: ${formatErrorMessage(error)}`, { cause: error });
   }
 }
 
@@ -146,8 +146,14 @@ function readApprovalToolCallRef(
 }
 
 function requireDeniedApproval(result: AuditRunInspectResult) {
-  const receipt = result.decisions.find(
-    (candidate) => candidate.source.owner === "operator_approvals",
+  const receipt = result.decisionDisplays.find(
+    (
+      candidate,
+    ): candidate is typeof candidate & {
+      provenance: { state: "verified"; producer: "operator-approval" };
+    } =>
+      candidate.provenance.state === "verified" &&
+      candidate.provenance.producer === "operator-approval",
   );
   if (!receipt) {
     throw new Error("audit inspection omitted the authoritative approval receipt");
@@ -156,9 +162,9 @@ function requireDeniedApproval(result: AuditRunInspectResult) {
     receipt.decision.outcome !== "denied" ||
     receipt.decision.reasonCode !== "operator_approval_denied_by_reviewer" ||
     receipt.enforcement.coverageState !== "enforced" ||
-    !receipt.enforcement.policyRefs.includes("operator-approval:human-decision") ||
+    receipt.enforcement.policyCount !== 2 ||
     receipt.enforcement.contextFieldsUsed.join(",") !== "contextId,executionId,runId" ||
-    receipt.enforcement.grantRefs.length !== 0 ||
+    receipt.enforcement.grantCount !== 0 ||
     receipt.remediation[0]?.code !== "review_and_request_again"
   ) {
     throw new Error("approval receipt did not preserve denial, enforcement, and remediation");
@@ -295,24 +301,24 @@ async function runProof(options: ProducerOptions): Promise<string> {
     ) {
       throw new Error("audit text omitted approval reason, durability, or remediation");
     }
-    const before = parseJson<AuditRunInspectResult>(
+    const before = parseJson(
       await gateway.runCli(["audit", "--run", runId, "--explain", "--json"]),
       "pre-restart decision inspection",
     );
     const receipt = requireDeniedApproval(before);
-    const firstPage = parseJson<AuditRunInspectResult>(
+    const firstPage = parseJson(
       await gateway.runCli(["audit", "--run", runId, "--explain", "--limit", "1", "--json"]),
       "first decision page",
     );
     if (firstPage.nextDecisionCursor?.startsWith("a:") !== true) {
       throw new Error("first decision page omitted its opaque approval cursor");
     }
-    const legacyResume = parseJson<AuditRunInspectResult>(
+    const legacyResume = parseJson(
       await gateway.runCli(["audit", "--run", runId, "--explain", "--cursor", "001", "--json"]),
       "legacy numeric decision continuation",
     );
     requireDeniedApproval(legacyResume);
-    const opaqueResume = parseJson<AuditRunInspectResult>(
+    const opaqueResume = parseJson(
       await gateway.runCli([
         "audit",
         "--run",
@@ -333,7 +339,7 @@ async function runProof(options: ProducerOptions): Promise<string> {
     assertNoGenericApprovalDuplicate(gateway);
 
     await gateway.restartAfterStateMutation(async () => {});
-    const after = parseJson<AuditRunInspectResult>(
+    const after = parseJson(
       await gateway.runCli(["audit", "--run", runId, "--explain", "--json"]),
       "post-restart decision inspection",
     );
@@ -355,7 +361,7 @@ async function runProof(options: ProducerOptions): Promise<string> {
             outcome: receipt.decision.outcome,
             reasonCode: receipt.decision.reasonCode,
             coverageState: receipt.enforcement.coverageState,
-            sourceOwner: receipt.source.owner,
+            provenanceProducer: receipt.provenance.producer,
             remediationCode: receipt.remediation[0]?.code,
           },
           firstAnswerPreserved: true,
@@ -436,7 +442,7 @@ if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
     .then((exitCode) => {
       process.exitCode = exitCode;
     })
-    .catch((error) => {
+    .catch((error: unknown) => {
       console.error(formatErrorMessage(error));
       process.exitCode = 1;
     });
diff --git a/test/e2e/qa-lab/runtime/agent-run-identity-inspection.ts b/test/e2e/qa-lab/runtime/agent-run-identity-inspection.ts
index 2c8fa353c102..b593aedf22c7 100644
--- a/test/e2e/qa-lab/runtime/agent-run-identity-inspection.ts
+++ b/test/e2e/qa-lab/runtime/agent-run-identity-inspection.ts
@@ -362,8 +362,9 @@ function assertJsonProjection(result: AuditRunInspectResult, runId: string) {
   ) {
     throw new Error("local agent run did not retain authoritative local-CLI ingress");
   }
-  const admission = result.decisions.find(
-    (receipt) => receipt.action.family === "run" && receipt.action.operation === "admission",
+  const admission = result.decisionDisplays.find(
+    (receipt) =>
+      receipt.provenance.state === "verified" && receipt.provenance.producer === "run-admission",
   );
   if (
     !admission ||
@@ -917,7 +918,7 @@ async function runProof(options: ProducerOptions): Promise<string> {
             contextId: row.context_id,
           })),
           coverage: before.coverage,
-          decision: before.decisions[0]?.decision,
+          decision: before.decisionDisplays[0]?.decision,
           contextSha256: sha256(beforeContext),
           byteEquivalentAfterRestart: true,
           byteEquivalentPersistedReadback: true,
diff --git a/test/e2e/qa-lab/runtime/codex-native-approval-receipt.e2e.test.ts b/test/e2e/qa-lab/runtime/codex-native-approval-receipt.e2e.test.ts
index d4292b0881f3..b20481416cd7 100644
--- a/test/e2e/qa-lab/runtime/codex-native-approval-receipt.e2e.test.ts
+++ b/test/e2e/qa-lab/runtime/codex-native-approval-receipt.e2e.test.ts
@@ -126,8 +126,10 @@ function assertNoGenericDuplicate(testInstance: OpenClawTestInstance, approvalId
 }
 
 function requireAllowedOnceReceipt(result: AuditRunInspectResult) {
-  const receipt = result.decisions.find(
-    (candidate) => candidate.source.owner === "operator_approvals",
+  const receipt = result.decisionDisplays.find(
+    (candidate) =>
+      candidate.provenance.state === "verified" &&
+      candidate.provenance.producer === "operator-approval",
   );
   expect(receipt).toMatchObject({
     decision: {
@@ -138,7 +140,7 @@ function requireAllowedOnceReceipt(result: AuditRunInspectResult) {
       coverageState: "enforced",
       contextFieldsUsed: ["contextId", "executionId", "runId"],
     },
-    source: { owner: "operator_approvals" },
+    provenance: { state: "verified", producer: "operator-approval" },
   });
   if (!receipt) {
     throw new Error("audit inspection omitted the operator approval receipt");
@@ -147,11 +149,11 @@ function requireAllowedOnceReceipt(result: AuditRunInspectResult) {
 }
 
 function summarizeAppServerLog(filePath: string) {
-  return readJsonLines(filePath).map((entry) => ({
-    id: entry.id,
-    method: entry.method,
-    ...(entry.id === "approval-private-native-approval" ? { result: entry.result } : {}),
-  }));
+  return readJsonLines(filePath).map((entry) =>
+    entry.id === "approval-private-native-approval"
+      ? { id: entry.id, method: entry.method, result: entry.result }
+      : { id: entry.id, method: entry.method },
+  );
 }
 
 async function connectApprovalReviewer(testInstance: OpenClawTestInstance) {
diff --git a/ui/src/e2e/activity-run-inspector.e2e.test.ts b/ui/src/e2e/activity-run-inspector.e2e.test.ts
index 6c13b81c4b4f..cb4dcf1234cc 100644
--- a/ui/src/e2e/activity-run-inspector.e2e.test.ts
+++ b/ui/src/e2e/activity-run-inspector.e2e.test.ts
@@ -10,105 +10,22 @@ import {
   startControlUiE2eServer,
   type ControlUiE2eServer,
 } from "../test-helpers/control-ui-e2e.ts";
+import {
+  decisionDisplay,
+  presentResult,
+  receiptPage,
+} from "./activity-run-inspector.test-fixtures.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 captureUiProof = process.env.OPENCLAW_CAPTURE_UI_PROOF === "1";
-const proofDir = path.resolve(".artifacts/control-ui-e2e/activity-run-inspector");
-const hmacRef = `hmac-sha256:v1:${"a".repeat(32)}:${"b".repeat(64)}`;
+const proofDir = path.resolve(".artifacts/control-ui-e2e/activity-run-inspector-r6");
 
 let browser: Browser;
 let server: ControlUiE2eServer;
 
-function presentResult(runId: string, executionId = "execution-safe-ref"): AuditRunInspectResult {
-  return {
-    schemaVersion: 1,
-    run: { runId, executionId, status: "known" },
-    identity: {
-      state: "present",
-      context: {
-        schemaVersion: 1,
-        contextId: "context-safe-ref",
-        executionId,
-        runId,
-        createdAt: 1_786_000_000_000,
-        trustDomain: { kind: "gateway-cell", domainRef: hmacRef, state: "present" },
-        invoker: { state: "absent" },
-        ingress: {
-          kind: "gateway-client",
-          boundary: "agent-command.gateway",
-          sourceRef: hmacRef,
-          state: "present",
-        },
-        agentPrincipal: {
-          kind: "agent",
-          domainRef: hmacRef,
-          principalRef: "main",
-          displayLabel: "Primary agent",
-        },
-        agentDefinition: { definitionRef: "main", state: "unknown" },
-        runtimeInstance: { runtimeRef: hmacRef, kind: "gateway", state: "unsupported" },
-        representedSubject: {
-          principal: { kind: "person", domainRef: hmacRef, principalRef: hmacRef },
-          state: "unknown",
-        },
-        sponsor: {
-          principal: { kind: "service", domainRef: hmacRef, principalRef: hmacRef },
-          state: "unsupported",
-        },
-        applicableGrants: [{ grantRef: hmacRef, state: "absent" }],
-        assurance: [
-          { kind: "runtime-binding", evidenceRef: hmacRef, strength: "boundary-verified" },
-        ],
-        lineage: { parentRunId: "parent-safe-ref", depth: 1 },
-        coverageState: "unattributed",
-        missingEvidence: ["invoker.principal"],
-      },
-    },
-    decisions: [
-      {
-        schemaVersion: 1,
-        receiptId: "receipt-safe-ref",
-        contextId: "context-safe-ref",
-        executionId,
-        runId,
-        occurredAt: 1_786_000_000_000,
-        action: {
-          family: "run",
-          operation: "admission",
-          summary: "Run admission was recorded without identity-aware evaluation.",
-        },
-        decision: {
-          outcome: "not-applicable",
-          reasonCode: "run_admission_identity_not_evaluated",
-        },
-        enforcement: {
-          coverageState: "unattributed",
-          policyRefs: [],
-          grantRefs: [],
-          contextFieldsUsed: [],
-        },
-        source: {
-          owner: "agent-command",
-          recordRef: "context-safe-ref",
-          decisionBoundary: "agent-command.run-admission",
-        },
-        missingEvidence: ["invoker.principal"],
-        remediation: [
-          {
-            code: "no_identity_enforcement_claimed",
-            text: "Treat this receipt as attribution only; it does not prove authorization.",
-          },
-        ],
-      },
-    ],
-    coverage: { state: "unattributed", missingEvidence: ["invoker.principal"] },
-    nextDecisionCursor: "1",
-  };
-}
-
 function unavailableResult(params: {
   state: "unknown" | "unsupported";
   reasonCode: string;
@@ -123,7 +40,7 @@ function unavailableResult(params: {
       missingEvidence: ["identity.context"],
       remediation: params.remediation ?? [],
     },
-    decisions: [],
+    decisionDisplays: [],
     coverage: { state: params.state, missingEvidence: ["identity.context"] },
   };
 }
@@ -150,7 +67,7 @@ function ambiguousResult(
         },
       ],
     },
-    decisions: [],
+    decisionDisplays: [],
     coverage: { state: "unknown", missingEvidence: ["execution.selection"] },
     ...(nextExecutionCursor ? { nextExecutionCursor } : {}),
   };
@@ -298,6 +215,486 @@ describeControlUiE2e("Control UI durable Activity run inspector", () => {
     }
   });
 
+  it("pages, deep-links, and safely explains approval and unsupported receipts", async () => {
+    const privateApprovalReceiptId = "U2_R6_BROWSER_APPROVAL_RECEIPT_ID_SECRET_315c";
+    const privateResolutionRef = "U2_R6_BROWSER_RESOLUTION_REF_SECRET_f907";
+    const privateMessageReceiptId = "U2_R6_BROWSER_MESSAGE_RECEIPT_ID_SECRET_761e";
+    const privateEventId = "U2_R6_BROWSER_EVENT_ID_SECRET_b442";
+    const allowed = decisionDisplay({
+      id: "approval-decision:101",
+      summary: "An exec approval allowed the requested action.",
+      outcome: "allowed",
+      reasonCode: "operator_approval_allowed_by_reviewer",
+      coverageState: "enforced",
+      remediation: "No follow-up is required.",
+    });
+    const denied = decisionDisplay({
+      id: "approval-decision:102",
+      summary: "An exec approval stopped the requested action.",
+      outcome: "denied",
+      reasonCode: "operator_approval_denied_by_reviewer",
+      coverageState: "enforced",
+      remediation: "Review the denial before requesting a new action.",
+    });
+    Object.assign(denied, {
+      receiptId: privateApprovalReceiptId,
+      resolutionRef: privateResolutionRef,
+      command: "rm -rf /private/operator-path",
+      arguments: { token: "credential-value" },
+      payload: "raw-payload",
+    });
+    const expired = decisionDisplay({
+      id: "approval-decision:103",
+      summary: "An exec approval expired before a decision arrived.",
+      outcome: "denied",
+      reasonCode: "operator_approval_expired",
+      coverageState: "enforced",
+      remediation: "Request the action again and resolve the new approval before its deadline.",
+    });
+    const cancelled = decisionDisplay({
+      id: "approval-decision:104",
+      summary: "An exec approval was cancelled when the run ended.",
+      outcome: "denied",
+      reasonCode: "operator_approval_cancelled_run_aborted",
+      coverageState: "enforced",
+      remediation: "Start a new run if the action is still needed.",
+    });
+    const unknown = decisionDisplay({
+      id: "approval-decision:105",
+      summary: "A retained approval could not be bound to this execution.",
+      outcome: "unknown",
+      reasonCode: "operator_approval_execution_link_missing",
+      coverageState: "unknown",
+      remediation: "Inspect the exact retained binding before trusting attribution.",
+    });
+    const unsupported = decisionDisplay({
+      id: "approval-decision:106",
+      summary: "This observation has no Phase 0 enforcement contract.",
+      outcome: "not-applicable",
+      reasonCode: "observation_enforcement_unsupported",
+      coverageState: "unsupported",
+      remediation: "Treat this as an observation, not an authorization decision.",
+    });
+    const delivered = decisionDisplay({
+      id: "message-decision:2000000000007",
+      summary: "An outbound message was delivered.",
+      outcome: "allowed",
+      reasonCode: "message_delivered",
+      coverageState: "attribution-only",
+      remediation: "No follow-up is required.",
+      producer: "message-delivery",
+      family: "message",
+      operation: "send",
+    });
+    Object.assign(delivered, {
+      receiptId: privateMessageReceiptId,
+      eventId: privateEventId,
+    });
+    const firstPage = receiptPage([allowed, denied], "a:10:2");
+    const secondPage = receiptPage([expired, cancelled, unknown, unsupported, delivered]);
+    const context = await newContext();
+    await context.addInitScript(() => {
+      const recordedUrls: string[] = [];
+      const instrument = (method: "pushState" | "replaceState") => {
+        const original = history[method].bind(history);
+        history[method] = ((data: unknown, unused: string, url?: string | URL | null) => {
+          if (url !== undefined && url !== null) {
+            recordedUrls.push(String(url));
+          }
+          original(data, unused, url);
+        }) as History[typeof method];
+      };
+      instrument("pushState");
+      instrument("replaceState");
+      Object.defineProperty(window, "activityHistoryUrls", { value: recordedUrls });
+    });
+    const page = await context.newPage();
+    const gateway = await installMockGateway(page, {
+      featureMethods: ["audit.run.inspect"],
+      methodResponses: {
+        "audit.run.inspect": {
+          cases: [
+            { match: { decisionCursor: "a:10:2" }, response: secondPage },
+            { match: { runId: "receipt-matrix" }, response: firstPage },
+          ],
+        },
+      },
+    });
+
+    try {
+      await page.goto(`${server.baseUrl}activity?view=run&run=receipt-matrix`);
+      await page.getByRole("list", { name: "Decision receipt list" }).waitFor();
+      await page.getByRole("heading", { name: "Receipt detail" }).waitFor();
+      await page.getByText("Allowed", { exact: true }).first().waitFor();
+      await page.getByText("Enforced", { exact: true }).first().waitFor();
+      await page.getByText("operator_approval_allowed_by_reviewer", { exact: true }).waitFor();
+      await page.getByText("Display provenance", { exact: true }).waitFor();
+      await page.getByText("Verified producer", { exact: true }).waitFor();
+      await page.getByText("operator-approval", { exact: true }).waitFor();
+      await page.getByText("No follow-up is required.", { exact: true }).waitFor();
+      expect(
+        await page
+          .getByText("Policy references used", { exact: true })
+          .locator("xpath=following-sibling::dd")
+          .textContent(),
+      ).toBe("1");
+      expect(
+        await page
+          .getByText("Grant references used", { exact: true })
+          .locator("xpath=following-sibling::dd")
+          .textContent(),
+      ).toBe("1");
+
+      const deniedLink = page.getByText(denied.action.summary!, { exact: true }).locator("..");
+      await deniedLink.focus();
+      await page.keyboard.press("Enter");
+      await page.getByText("operator_approval_denied_by_reviewer", { exact: true }).waitFor();
+      expect(new URL(page.url()).searchParams.get("receipt")).toBe("approval-decision:102");
+      await page.reload();
+      await page.getByText("operator_approval_denied_by_reviewer", { exact: true }).waitFor();
+
+      await page.getByRole("button", { name: "Load more receipts" }).click();
+      expect((await gateway.getRequests("audit.run.inspect")).at(-1)?.params).toMatchObject({
+        runId: "receipt-matrix",
+        decisionCursor: "a:10:2",
+        decisionLimit: 50,
+      });
+      await page.getByText(expired.action.summary!, { exact: true }).click();
+      await page.getByText("operator_approval_expired", { exact: true }).waitFor();
+      const selectedUrl = new URL(page.url());
+      expect(selectedUrl.searchParams.get("receipt")).toBe("approval-decision:103");
+      expect(selectedUrl.searchParams.get("decision")).toBe("a:10:2");
+      await page.reload();
+      await page.getByText("operator_approval_expired", { exact: true }).waitFor();
+      expect((await gateway.getRequests("audit.run.inspect")).at(-1)?.params).toMatchObject({
+        runId: "receipt-matrix",
+        decisionCursor: "a:10:2",
+        decisionLimit: 50,
+      });
+
+      for (const [receipt, reasonCode] of [
+        [cancelled, "operator_approval_cancelled_run_aborted"],
+        [unknown, "operator_approval_execution_link_missing"],
+        [unsupported, "observation_enforcement_unsupported"],
+      ] as const) {
+        await page.getByText(receipt.action.summary!, { exact: true }).click();
+        await page.getByText(reasonCode, { exact: true }).waitFor();
+      }
+      await page.getByText("Unknown", { exact: true }).first().waitFor();
+      await page.getByText("Unsupported", { exact: true }).first().waitFor();
+      await page.getByText(delivered.action.summary!, { exact: true }).click();
+      await page.getByText("message_delivered", { exact: true }).waitFor();
+      expect(new URL(page.url()).searchParams.get("receipt")).toBe(
+        "message-decision:2000000000007",
+      );
+      const surfaces = await page.locator("body").evaluate((body) => {
+        const elements = [body, ...body.querySelectorAll<HTMLElement>("*")];
+        const historyUrls = (window as typeof window & { activityHistoryUrls?: readonly string[] })
+          .activityHistoryUrls;
+        return {
+          // oxlint-disable-next-line unicorn/prefer-dom-node-text-content -- innerText separately proves rendered visible text.
+          visibleText: body instanceof HTMLElement ? body.innerText : "",
+          textContent: body.textContent ?? "",
+          aria: elements
+            .flatMap((element) =>
+              ["aria-label", "aria-labelledby", "aria-describedby", "title", "alt"].map((name) =>
+                element.getAttribute(name),
+              ),
+            )
+            .filter((value): value is string => value !== null)
+            .join("\n"),
+          hrefs: elements
+            .filter((element): element is HTMLAnchorElement => element instanceof HTMLAnchorElement)
+            .flatMap((link) => [link.getAttribute("href") ?? "", link.href])
+            .join("\n"),
+          location: location.href,
+          historyState: JSON.stringify(history.state),
+          historyUrls: [...(historyUrls ?? [])].join("\n"),
+        };
+      });
+      const accessibilityTree = await page.locator("body").ariaSnapshot();
+      for (const hidden of [
+        "hidden-action-id",
+        "hidden-resource-id",
+        "hidden-target-id",
+        "hidden-evaluator-id",
+        "hidden-policy-id",
+        "hidden-grant-id",
+        "hidden-record-id",
+        "rm -rf",
+        "/private/operator-path",
+        "credential-value",
+        "raw-payload",
+        privateApprovalReceiptId,
+        privateResolutionRef,
+        privateMessageReceiptId,
+        privateEventId,
+      ]) {
+        for (const surface of [...Object.values(surfaces), accessibilityTree]) {
+          expect(surface).not.toContain(hidden);
+        }
+      }
+      await screenshot(page, "16-receipt-detail-message.png");
+    } finally {
+      await context.close();
+    }
+  });
+
+  it("keeps generic receipt prose out of every Activity presentation surface", async () => {
+    const secrets = [
+      "U2_R6_BROWSER_RECEIPT_ID_SECRET_5e3d70",
+      "U2_R6_BROWSER_ACTION_ID_SECRET_4d1ac2",
+      "U2_R6_BROWSER_CONTEXT_ID_SECRET_a11c42",
+      "U2_R6_BROWSER_EXECUTION_ID_SECRET_5d00be",
+      "U2_R6_BROWSER_RUN_ID_SECRET_808c3e",
+      "U2_R6_BROWSER_RESOURCE_REF_SECRET_0ad831",
+      "U2_R6_BROWSER_TARGET_REF_SECRET_04f9e0",
+      "U2_R6_BROWSER_RECORD_REF_SECRET_3ab89a",
+      "U2_R6_BROWSER_EVALUATOR_REF_SECRET_1b8d53",
+      "U2_R6_BROWSER_OWNER_SECRET_ec0ffe",
+      "U2_R6_BROWSER_SUMMARY_SECRET_9fe28a",
+      "U2_R6_BROWSER_CODE_SECRET_724ac1",
+      "U2_R6_BROWSER_TEXT_SECRET_31db80",
+      "U2_R6_BROWSER_POLICY_REF_SECRET_30f6ac",
+      "U2_R6_BROWSER_GRANT_REF_SECRET_79d4e1",
+      "U2_R6_BROWSER_REASON_SECRET_1114e6",
+      "U2_R6_BROWSER_COMMAND_PATH_TOOL_INPUT_PERMISSION_METADATA_SECRET_b7114d",
+    ];
+    const response = receiptPage([
+      {
+        schemaVersion: 1,
+        selectorId: "decision-fact:1",
+        occurredAt: 1_786_000_000_000,
+        action: { family: "decision", operation: "record" },
+        decision: { outcome: "unknown", reasonCode: "decision_fact_display_unverified" },
+        enforcement: {
+          coverageState: "unknown",
+          policyCount: 0,
+          grantCount: 0,
+          contextFieldsUsed: [],
+        },
+        provenance: { state: "unverified" },
+        missingEvidence: ["decision.display_provenance"],
+        remediation: [],
+      },
+    ]);
+    expect(response).not.toHaveProperty("decisions");
+
+    const context = await newContext({ video: true });
+    await context.addInitScript(() => {
+      const recordedUrls: string[] = [];
+      const instrument = (method: "pushState" | "replaceState") => {
+        const original = history[method].bind(history);
+        history[method] = ((data: unknown, unused: string, url?: string | URL | null) => {
+          if (url !== undefined && url !== null) {
+            recordedUrls.push(String(url));
+          }
+          original(data, unused, url);
+        }) as History[typeof method];
+      };
+      instrument("pushState");
+      instrument("replaceState");
+      Object.defineProperty(window, "activityHistoryUrls", { value: recordedUrls });
+    });
+    const page = await context.newPage();
+    await installMockGateway(page, {
+      featureMethods: ["audit.run.inspect"],
+      methodResponses: { "audit.run.inspect": response },
+    });
+
+    try {
+      await page.goto(`${server.baseUrl}activity?view=run&run=receipt-matrix`);
+      await page.getByRole("heading", { name: "Receipt detail" }).waitFor();
+      await page.getByText("Unknown", { exact: true }).first().waitFor();
+      await page
+        .getByText("Receipt-controlled explanations and next steps are hidden", {
+          exact: false,
+        })
+        .waitFor();
+      expect(
+        await page
+          .getByText("Policy references used", { exact: true })
+          .locator("xpath=following-sibling::dd")
+          .textContent(),
+      ).toBe("0");
+      expect(
+        await page
+          .getByText("Grant references used", { exact: true })
+          .locator("xpath=following-sibling::dd")
+          .textContent(),
+      ).toBe("0");
+
+      const surfaces = await page.locator("body").evaluate((body) => {
+        const elements = [body, ...body.querySelectorAll<HTMLElement>("*")];
+        const aria = elements.flatMap((element) =>
+          ["aria-label", "aria-labelledby", "aria-describedby", "title", "alt"]
+            .map((name) => element.getAttribute(name))
+            .filter((value): value is string => value !== null),
+        );
+        const historyUrls = (window as typeof window & { activityHistoryUrls?: readonly string[] })
+          .activityHistoryUrls;
+        return {
+          // oxlint-disable-next-line unicorn/prefer-dom-node-text-content -- innerText separately proves rendered visible text.
+          visibleText: body instanceof HTMLElement ? body.innerText : "",
+          textContent: body.textContent ?? "",
+          aria: aria.join("\n"),
+          hrefs: elements
+            .filter((element): element is HTMLAnchorElement => element instanceof HTMLAnchorElement)
+            .flatMap((link) => [link.getAttribute("href") ?? "", link.href])
+            .join("\n"),
+          location: location.href,
+          historyState: JSON.stringify(history.state),
+          historyUrls: [...(historyUrls ?? [])].join("\n"),
+        };
+      });
+      const accessibilityTree = await page.locator("body").ariaSnapshot();
+      for (const secret of [...secrets, "operator_approvals"]) {
+        for (const surface of [...Object.values(surfaces), accessibilityTree]) {
+          expect(surface).not.toContain(secret);
+        }
+      }
+      await screenshot(page, "18-unverified-receipt-privacy.png");
+    } finally {
+      await context.close();
+    }
+  });
+
+  it("keeps loaded receipts visible when later-page inspection fails", async () => {
+    const context = await newContext();
+    const page = await context.newPage();
+    await installMockGateway(page, {
+      featureMethods: ["audit.run.inspect"],
+      methodResponses: {
+        "audit.run.inspect": {
+          cases: [
+            {
+              match: { decisionCursor: "a:10:2" },
+              response: {
+                __mockError: {
+                  code: "INVALID_REQUEST",
+                  message: "decision cursor is no longer retained",
+                },
+              },
+            },
+            {
+              match: { runId: "receipt-page-error" },
+              response: {
+                ...receiptPage(
+                  [
+                    decisionDisplay({
+                      id: "approval-decision:107",
+                      summary: "A denied approval remains visible.",
+                      outcome: "denied",
+                      reasonCode: "operator_approval_denied_by_reviewer",
+                      coverageState: "enforced",
+                      remediation: "Review the recorded denial.",
+                    }),
+                  ],
+                  "a:10:2",
+                ),
+                run: {
+                  runId: "receipt-page-error",
+                  executionId: "execution-safe-ref",
+                  status: "known",
+                },
+              },
+            },
+          ],
+        },
+      },
+    });
+
+    try {
+      await page.goto(`${server.baseUrl}activity?view=run&run=receipt-page-error`);
+      await page.getByText("A denied approval remains visible.", { exact: true }).first().waitFor();
+      await page.getByRole("button", { name: "Load more receipts" }).click();
+      await page
+        .getByRole("alert")
+        .getByText("More receipts could not be loaded", { exact: false })
+        .waitFor();
+      await page.getByText("A denied approval remains visible.", { exact: true }).first().waitFor();
+    } finally {
+      await context.close();
+    }
+  });
+
+  it("restarts stale receipt deep links on page one while preserving the exact selector", async () => {
+    for (const scenario of [
+      { kind: "run", id: "run:stale/deep-link" },
+      { kind: "execution", id: "execution:stale/deep-link" },
+    ] as const) {
+      const context = await newContext();
+      const page = await context.newPage();
+      const receiptId = `private-receipt-${scenario.kind}`;
+      const decisionCursor = `a:1786000000000:${scenario.kind === "run" ? "41" : "42"}`;
+      const firstPage = presentResult(
+        scenario.kind === "run" ? scenario.id : "run-for-exact-execution",
+        scenario.kind === "execution" ? scenario.id : "execution-for-run",
+      );
+      const gateway = await installMockGateway(page, {
+        featureMethods: ["audit.run.inspect"],
+        methodResponses: {
+          "audit.run.inspect": {
+            cases: [
+              {
+                match: { decisionCursor },
+                response: {
+                  __mockError: {
+                    code: "INVALID_REQUEST",
+                    message: "decision cursor is no longer retained",
+                  },
+                },
+              },
+              { match: { [`${scenario.kind}Id`]: scenario.id }, response: firstPage },
+            ],
+          },
+        },
+      });
+
+      try {
+        const search = new URLSearchParams({
+          view: "run",
+          [scenario.kind]: scenario.id,
+          receipt: receiptId,
+          decision: decisionCursor,
+        });
+        await page.goto(`${server.baseUrl}activity?${search.toString()}`);
+        await page.getByRole("heading", { name: "Run inspection failed" }).waitFor();
+        const restart = page.getByRole("button", { name: "Restart inspection" });
+        await restart.waitFor();
+        expect(await page.getByRole("button", { name: "Retry inspection" }).count()).toBe(0);
+        const errorText = (await page.locator(".run-inspector__panel").textContent()) ?? "";
+        expect(errorText).not.toContain(receiptId);
+        expect(errorText).not.toContain(decisionCursor);
+
+        const requestCount = (await gateway.getRequests("audit.run.inspect")).length;
+        await restart.focus();
+        await expect
+          .poll(() => page.evaluate(() => document.activeElement?.textContent?.trim()))
+          .toBe("Restart inspection");
+        await page.keyboard.press("Enter");
+        await page.getByRole("heading", { name: "Identity and authority" }).waitFor();
+        const request = await gateway.waitForRequest("audit.run.inspect", { after: requestCount });
+        const expectedParams = {
+          [`${scenario.kind}Id`]: scenario.id,
+          decisionLimit: 50,
+          ...(scenario.kind === "run" ? { executionLimit: 50 } : {}),
+        };
+        expect(request.params).toEqual(expectedParams);
+        expect(request.params).not.toHaveProperty("decisionCursor");
+        const restartedUrl = new URL(page.url());
+        expect(restartedUrl.searchParams.get(scenario.kind)).toBe(scenario.id);
+        expect(restartedUrl.searchParams.get(scenario.kind === "run" ? "execution" : "run")).toBe(
+          null,
+        );
+        expect(restartedUrl.searchParams.get("receipt")).toBeNull();
+        expect(restartedUrl.searchParams.get("decision")).toBeNull();
+      } finally {
+        await context.close();
+      }
+    }
+  });
+
   it("keeps a populated Live activity stream bounded after adding the mode switcher", async () => {
     const context = await newContext();
     const page = await context.newPage();
@@ -402,9 +799,10 @@ describeControlUiE2e("Control UI durable Activity run inspector", () => {
     try {
       await page.goto(`${server.baseUrl}activity?view=run&run=${encodeURIComponent(runId)}`);
       const inspector = page.locator(".run-inspector");
-      const finalReceiptContent = page.getByText("Additional decision receipts are available", {
-        exact: false,
-      });
+      const finalReceiptContent = page.getByText(
+        "Treat this receipt as attribution only; it does not prove authorization.",
+        { exact: true },
+      );
       await finalReceiptContent.waitFor({ state: "attached" });
 
       const desktopLayout = await inspector.evaluate((element) => ({
diff --git a/ui/src/e2e/activity-run-inspector.test-fixtures.ts b/ui/src/e2e/activity-run-inspector.test-fixtures.ts
new file mode 100644
index 000000000000..bca159563a84
--- /dev/null
+++ b/ui/src/e2e/activity-run-inspector.test-fixtures.ts
@@ -0,0 +1,136 @@
+import type {
+  AuditRunInspectResult,
+  DecisionReceiptDisplayV1,
+} from "../../../packages/gateway-protocol/src/schema/audit-run.js";
+
+const hmacRef = `hmac-sha256:v1:${"a".repeat(32)}:${"b".repeat(64)}`;
+
+export function presentResult(
+  runId: string,
+  executionId = "execution-safe-ref",
+): AuditRunInspectResult {
+  return {
+    schemaVersion: 1,
+    run: { runId, executionId, status: "known" },
+    identity: {
+      state: "present",
+      context: {
+        schemaVersion: 1,
+        contextId: "context-safe-ref",
+        executionId,
+        runId,
+        createdAt: 1_786_000_000_000,
+        trustDomain: { kind: "gateway-cell", domainRef: hmacRef, state: "present" },
+        invoker: { state: "absent" },
+        ingress: {
+          kind: "gateway-client",
+          boundary: "agent-command.gateway",
+          sourceRef: hmacRef,
+          state: "present",
+        },
+        agentPrincipal: {
+          kind: "agent",
+          domainRef: hmacRef,
+          principalRef: "main",
+          displayLabel: "Primary agent",
+        },
+        agentDefinition: { definitionRef: "main", state: "unknown" },
+        runtimeInstance: { runtimeRef: hmacRef, kind: "gateway", state: "unsupported" },
+        representedSubject: {
+          principal: { kind: "person", domainRef: hmacRef, principalRef: hmacRef },
+          state: "unknown",
+        },
+        sponsor: {
+          principal: { kind: "service", domainRef: hmacRef, principalRef: hmacRef },
+          state: "unsupported",
+        },
+        applicableGrants: [{ grantRef: hmacRef, state: "absent" }],
+        assurance: [
+          { kind: "runtime-binding", evidenceRef: hmacRef, strength: "boundary-verified" },
+        ],
+        lineage: { parentRunId: "parent-safe-ref", depth: 1 },
+        coverageState: "unattributed",
+        missingEvidence: ["invoker.principal"],
+      },
+    },
+    decisionDisplays: [
+      {
+        schemaVersion: 1,
+        selectorId: "receipt-safe-ref",
+        occurredAt: 1_786_000_000_000,
+        action: {
+          family: "run",
+          operation: "admission",
+          summary: "Run admission was recorded without identity-aware evaluation.",
+        },
+        decision: {
+          outcome: "not-applicable",
+          reasonCode: "run_admission_identity_not_evaluated",
+        },
+        enforcement: {
+          coverageState: "unattributed",
+          policyCount: 0,
+          grantCount: 0,
+          contextFieldsUsed: [],
+        },
+        provenance: { state: "verified", producer: "run-admission" },
+        missingEvidence: ["invoker.principal"],
+        remediation: [
+          {
+            code: "no_identity_enforcement_claimed",
+            text: "Treat this receipt as attribution only; it does not prove authorization.",
+          },
+        ],
+      },
+    ],
+    coverage: { state: "unattributed", missingEvidence: ["invoker.principal"] },
+    nextDecisionCursor: "1",
+  };
+}
+
+export function decisionDisplay(params: {
+  id: string;
+  summary: string;
+  outcome: DecisionReceiptDisplayV1["decision"]["outcome"];
+  reasonCode: string;
+  coverageState: DecisionReceiptDisplayV1["enforcement"]["coverageState"];
+  remediation: string;
+  producer?: "operator-approval" | "message-delivery";
+  family?: string;
+  operation?: string;
+}): DecisionReceiptDisplayV1 {
+  return {
+    schemaVersion: 1,
+    selectorId: params.id,
+    occurredAt: 1_786_000_000_000,
+    action: {
+      family: params.family ?? "exec",
+      operation: params.operation ?? "approval",
+      summary: params.summary,
+    },
+    decision: { outcome: params.outcome, reasonCode: params.reasonCode },
+    enforcement: {
+      coverageState: params.coverageState,
+      policyCount: 1,
+      grantCount: 1,
+      contextFieldsUsed: ["contextId", "executionId", "runId"],
+    },
+    provenance: { state: "verified", producer: params.producer ?? "operator-approval" },
+    missingEvidence: params.coverageState === "enforced" ? [] : ["decision.execution_link"],
+    remediation: [{ code: "safe_next_step", text: params.remediation }],
+  };
+}
+
+export function receiptPage(
+  decisionDisplays: DecisionReceiptDisplayV1[],
+  nextDecisionCursor?: string,
+): AuditRunInspectResult {
+  const result = presentResult("receipt-matrix");
+  const { nextDecisionCursor: _nextDecisionCursor, ...base } = result;
+  return {
+    ...base,
+    decisionDisplays,
+    coverage: { state: "unknown", missingEvidence: ["decision.execution_link"] },
+    ...(nextDecisionCursor ? { nextDecisionCursor } : {}),
+  };
+}
diff --git a/ui/src/i18n/locales/en-activity.ts b/ui/src/i18n/locales/en-activity.ts
index a5a491bb7df5..2ae97ecb9ef4 100644
--- a/ui/src/i18n/locales/en-activity.ts
+++ b/ui/src/i18n/locales/en-activity.ts
@@ -97,6 +97,7 @@ const enActivity = {
       values: {
         label: "Label",
         kind: "Kind",
+        operation: "Operation",
         principalReference: "Principal reference",
         domainReference: "Domain reference",
         owningBoundary: "Owning boundary",
@@ -130,9 +131,43 @@ const enActivity = {
       decisions: {
         heading: "Decision receipts",
         none: "No decision receipts were returned for this bounded page.",
-        returned: "The Gateway returned {count} receipt summaries for this bounded page.",
-        more: "Additional decision receipts are available. This inspector intentionally shows only the bounded first page; use the audit CLI with a cursor for later pages.",
+        returned: "Showing {count} retained decision receipts.",
+        listLabel: "Decision receipt list",
+        inspectLabel: "{summary}. Outcome: {outcome}. Evidence classification: {classification}.",
+        detailHeading: "Receipt detail",
+        requestedHeading: "What was requested",
+        outcomeHeading: "What happened",
+        outcomeLabel: "Outcome",
+        classificationLabel: "Evidence classification",
+        reasonLabel: "Recorded reason",
+        occurredAtLabel: "Recorded at",
+        ownerHeading: "Display provenance",
+        durableOwnerLabel: "Verified producer",
+        boundaryLabel: "Decision boundary",
+        ownerNote:
+          "The Gateway exposes explanations only from a verified owning call path. Receipt-controlled explanations and next steps are hidden; the Control UI does not infer trust from receipt metadata.",
+        evidenceHeading: "Evidence limits",
+        contextFieldsLabel: "Context fields used",
+        noContextFields: "No context fields were recorded as used.",
+        policyCountLabel: "Policy references used",
+        grantCountLabel: "Grant references used",
+        notFoundTitle: "Receipt not found on this page",
+        notFoundDescription:
+          "The selected receipt is not present in this retained page. Return to the first page or use a current receipt link.",
+        readOnly:
+          "Decision receipts are read-only. This view cannot approve, edit, or repeat an action.",
+        more: "Additional decision receipts are available.",
+        loadMore: "Load more receipts",
+        loadingMore: "Loading receipts…",
+        loadMoreError:
+          "More receipts could not be loaded. The receipts already shown remain unchanged.",
         bounded: "Decision inspection is bounded to at most 50 records per request.",
+        outcomes: {
+          allowed: "Allowed",
+          denied: "Denied",
+          notApplicable: "Not applicable",
+          unknown: "Unknown",
+        },
       },
       diagnosticReason: "Diagnostic reason:",
       diagnostic: {
@@ -211,6 +246,7 @@ const enActivity = {
             "The Gateway could not return this diagnostic projection. No identity facts were inferred from Live activity.",
         },
       },
+      restart: "Restart inspection",
       retry: "Retry inspection",
     },
   },
diff --git a/ui/src/pages/activity/activity-page.test.ts b/ui/src/pages/activity/activity-page.test.ts
index 1f3f7930a714..3620c6fb8473 100644
--- a/ui/src/pages/activity/activity-page.test.ts
+++ b/ui/src/pages/activity/activity-page.test.ts
@@ -1,13 +1,29 @@
 /* @vitest-environment jsdom */
 
+import { GatewayProtocolRequestError } from "@openclaw/gateway-client/browser";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import type { AuditRunInspectResult } from "../../../../packages/gateway-protocol/src/schema/audit-run.js";
+import { GatewayRequestError, type GatewayBrowserClient } from "../../api/gateway.ts";
 import type { ApplicationContext, ApplicationGatewaySnapshot } from "../../app/context.ts";
+import type { RunInspectorState } from "./run-inspector-model.ts";
 import type { ActivityEntry } from "./tool-activity.ts";
 import "./activity-page.ts";
 
 type TestActivityPage = HTMLElement & {
   context: ApplicationContext;
   entries: ActivityEntry[];
+  routeData: {
+    mode: "run";
+    selector: { kind: "run"; id: string };
+    selectorId: string | null;
+    decisionCursor: string | null;
+  };
+  runInspector: RunInspectorState;
+  loadRunInspector: (
+    gateway: ApplicationContext["gateway"],
+    client: GatewayBrowserClient,
+    selector: { kind: "run"; id: string },
+  ) => Promise<void>;
   subscriptions: {
     hostConnected: () => void;
     hostUpdate: () => void;
@@ -72,4 +88,90 @@ describe("ActivityPage gateway lifecycle", () => {
 
     page.subscriptions.hostDisconnected();
   });
+
+  it("stores the safe-only inspection response directly", async () => {
+    const result = {
+      schemaVersion: 1,
+      run: { runId: "run-1", status: "unknown" },
+      identity: {
+        state: "unknown",
+        reasonCode: "run_not_found",
+        missingEvidence: ["run.record"],
+        remediation: [],
+      },
+      decisionDisplays: [],
+      coverage: { state: "unknown", missingEvidence: ["run.record"] },
+    } satisfies AuditRunInspectResult;
+    const client = { request: vi.fn(async () => result) } as unknown as GatewayBrowserClient;
+    const activeGateway = {
+      snapshot: { client, phase: "connected" },
+    } as unknown as ApplicationContext["gateway"];
+    const page = document.createElement("openclaw-activity-page") as TestActivityPage;
+    page.context = { gateway: activeGateway } as unknown as ApplicationContext;
+    page.routeData = {
+      mode: "run",
+      selector: { kind: "run", id: "run-1" },
+      selectorId: null,
+      decisionCursor: null,
+    };
+
+    await page.loadRunInspector(activeGateway, client, page.routeData.selector);
+
+    expect(page.runInspector.status).toBe("ready");
+    if (page.runInspector.status === "ready") {
+      expect(page.runInspector.result).toBe(result);
+    }
+  });
+
+  it.each([
+    [
+      "protocol request",
+      new GatewayProtocolRequestError({
+        code: "INVALID_REQUEST",
+        message: "decision cursor is no longer retained",
+      }),
+      "restart",
+    ],
+    [
+      "UI Gateway request",
+      new GatewayRequestError({
+        code: "INVALID_REQUEST",
+        message: "decision cursor is no longer retained",
+      }),
+      "restart",
+    ],
+    [
+      "retryable invalid request",
+      new GatewayRequestError({
+        code: "INVALID_REQUEST",
+        message: "temporarily unavailable",
+        retryable: true,
+      }),
+      "retry",
+    ],
+    [
+      "non-invalid request",
+      new GatewayProtocolRequestError({ code: "UNAVAILABLE", message: "gateway unavailable" }),
+      "retry",
+    ],
+  ] as const)("classifies a %s cursor failure", async (_label, error, recovery) => {
+    const client = {
+      request: vi.fn(() => Promise.reject(error)),
+    } as unknown as GatewayBrowserClient;
+    const activeGateway = {
+      snapshot: { client, phase: "connected" },
+    } as unknown as ApplicationContext["gateway"];
+    const page = document.createElement("openclaw-activity-page") as TestActivityPage;
+    page.context = { gateway: activeGateway } as unknown as ApplicationContext;
+    page.routeData = {
+      mode: "run",
+      selector: { kind: "run", id: "run-1" },
+      selectorId: "receipt-1",
+      decisionCursor: "cursor-1",
+    };
+
+    await page.loadRunInspector(activeGateway, client, page.routeData.selector);
+
+    expect(page.runInspector).toEqual({ status: "error", recovery });
+  });
 });
diff --git a/ui/src/pages/activity/activity-page.ts b/ui/src/pages/activity/activity-page.ts
index 50054205df72..67f2fdd289be 100644
--- a/ui/src/pages/activity/activity-page.ts
+++ b/ui/src/pages/activity/activity-page.ts
@@ -1,4 +1,5 @@
 import { consume } from "@lit/context";
+import { asNullableRecord as asRecord } from "@openclaw/normalization-core/record-coerce";
 import { html, nothing, type PropertyValues } from "lit";
 import { property, state } from "lit/decorators.js";
 import type { AuditRunInspectResult } from "../../../../packages/gateway-protocol/src/schema/audit-run.js";
@@ -30,6 +31,9 @@ import { OpenClawLightDomElement } from "../../lit/openclaw-element.ts";
 import { StreamAutoFollowController } from "../../lit/stream-auto-follow-controller.ts";
 import { SubscriptionsController } from "../../lit/subscriptions-controller.ts";
 import {
+  activityRunInspectorSearch,
+  mergeDecisionPage,
+  receiptPageCursors,
   resolveActivityRouteData,
   type ActivityRouteData,
   type RunInspectorSelector,
@@ -56,6 +60,21 @@ function selectorKey(selector: RunInspectorSelector | null): string | null {
   return selector ? `${selector.kind}:${selector.id}` : null;
 }
 
+function inspectorRequestKey(route: ActivityRouteData): string | null {
+  if (route.mode !== "run" || !route.selector) {
+    return null;
+  }
+  return `${selectorKey(route.selector)}:${route.decisionCursor ?? ""}`;
+}
+
+function isExpiredDecisionCursorError(error: unknown): boolean {
+  const record = asRecord(error);
+  return (
+    (record?.gatewayCode === "INVALID_REQUEST" || record?.code === "INVALID_REQUEST") &&
+    record.retryable !== true
+  );
+}
+
 class ActivityPage extends OpenClawLightDomElement {
   @consume({ context: applicationContext, subscribe: true })
   private context!: ApplicationContext;
@@ -163,7 +182,7 @@ class ActivityPage extends OpenClawLightDomElement {
   private bindInspectorRoute() {
     const route = this.routeData;
     const selector = route?.mode === "run" ? route.selector : null;
-    const nextSelectorKey = selectorKey(selector);
+    const nextSelectorKey = inspectorRequestKey(route);
     if (nextSelectorKey === this.inspectorSelectorKey && route?.mode === "run") {
       return;
     }
@@ -198,7 +217,7 @@ class ActivityPage extends OpenClawLightDomElement {
       this.runInspector = { status: "empty" };
       return;
     }
-    this.inspectorSelectorKey = selectorKey(selector);
+    this.inspectorSelectorKey = inspectorRequestKey(route);
     if (snapshot.phase !== "connected" || !snapshot.client) {
       this.cancelInspectorRequest();
       this.inspectorClient = null;
@@ -240,24 +259,25 @@ class ActivityPage extends OpenClawLightDomElement {
     gateway: ApplicationContext["gateway"],
     client: GatewayBrowserClient,
     selector: RunInspectorSelector,
-    previousResult?: AuditRunInspectResult,
+    previousState?: Extract<RunInspectorState, { status: "ready" }>,
   ) {
     this.cancelInspectorRequest();
     const epoch = this.inspectorEpoch;
     const abort = new AbortController();
     this.inspectorAbort = abort;
     this.inspectorClient = client;
-    this.runInspector = previousResult
-      ? { status: "ready", result: previousResult, executionPageStatus: "loading" }
+    this.runInspector = previousState
+      ? { ...previousState, executionPageStatus: "loading" }
       : { status: "loading", waitingForGateway: false };
-    const requestSelectorKey = selectorKey(selector);
+    const requestSelectorKey = inspectorRequestKey(this.routeData);
     const isCurrent = () =>
       this.inspectorEpoch === epoch &&
       this.context.gateway === gateway &&
       gateway.snapshot.client === client &&
       gateway.snapshot.phase === "connected" &&
       this.routeData?.mode === "run" &&
-      selectorKey(this.routeData.selector) === requestSelectorKey;
+      inspectorRequestKey(this.routeData) === requestSelectorKey;
+    const decisionCursor = this.routeData.mode === "run" ? this.routeData.decisionCursor : null;
     try {
       const params =
         selector.kind === "run"
@@ -265,21 +285,26 @@ class ActivityPage extends OpenClawLightDomElement {
               runId: selector.id,
               decisionLimit: 50,
               executionLimit: 50,
-              ...(previousResult?.nextExecutionCursor
-                ? { executionCursor: previousResult.nextExecutionCursor }
+              ...(decisionCursor ? { decisionCursor } : {}),
+              ...(previousState?.result.nextExecutionCursor
+                ? { executionCursor: previousState.result.nextExecutionCursor }
                 : {}),
             }
-          : { executionId: selector.id, decisionLimit: 50 };
+          : {
+              executionId: selector.id,
+              decisionLimit: 50,
+              ...(decisionCursor ? { decisionCursor } : {}),
+            };
       const result = await client.request<AuditRunInspectResult>("audit.run.inspect", params, {
         signal: abort.signal,
       });
       if (isCurrent()) {
         if (
-          previousResult?.identity.state === "ambiguous" &&
+          previousState?.result.identity.state === "ambiguous" &&
           result.identity.state === "ambiguous"
         ) {
           const candidates = new Map(
-            previousResult.identity.candidates.map((candidate) => [
+            previousState.result.identity.candidates.map((candidate) => [
               candidate.executionId,
               candidate,
             ]),
@@ -293,9 +318,17 @@ class ActivityPage extends OpenClawLightDomElement {
               ...result,
               identity: { ...result.identity, candidates: [...candidates.values()] },
             },
+            receiptPageCursors: previousState.receiptPageCursors,
           };
         } else {
-          this.runInspector = { status: "ready", result };
+          this.runInspector = {
+            status: "ready",
+            result,
+            receiptPageCursors: receiptPageCursors(
+              result.decisionDisplays,
+              decisionCursor ?? undefined,
+            ),
+          };
         }
       }
     } catch (error) {
@@ -306,9 +339,13 @@ class ActivityPage extends OpenClawLightDomElement {
         ? { status: "unauthorized" }
         : this.isUnknownInspectMethod(error)
           ? { status: "unsupported" }
-          : previousResult
-            ? { status: "ready", result: previousResult, executionPageStatus: "error" }
-            : { status: "error" };
+          : previousState
+            ? { ...previousState, executionPageStatus: "error" }
+            : {
+                status: "error",
+                recovery:
+                  decisionCursor && isExpiredDecisionCursorError(error) ? "restart" : "retry",
+              };
     } finally {
       if (this.inspectorAbort === abort) {
         this.inspectorAbort = null;
@@ -336,10 +373,88 @@ class ActivityPage extends OpenClawLightDomElement {
       this.context.gateway,
       snapshot.client,
       route.selector,
-      inspectorState.result,
+      inspectorState,
     );
   }
 
+  private loadMoreDecisions() {
+    const route = this.routeData;
+    const gateway = this.context.gateway;
+    const snapshot = gateway.snapshot;
+    const inspectorState = this.runInspector;
+    if (
+      route.mode !== "run" ||
+      !route.selector ||
+      snapshot.phase !== "connected" ||
+      !snapshot.client ||
+      inspectorState.status !== "ready" ||
+      inspectorState.decisionPageStatus === "loading" ||
+      inspectorState.result.identity.state !== "present" ||
+      !inspectorState.result.nextDecisionCursor
+    ) {
+      return;
+    }
+    const cursor = inspectorState.result.nextDecisionCursor;
+    const selector = route.selector;
+    const client = snapshot.client;
+    const requestSelectorKey = inspectorRequestKey(route);
+    this.cancelInspectorRequest();
+    const epoch = this.inspectorEpoch;
+    const abort = new AbortController();
+    this.inspectorAbort = abort;
+    this.runInspector = { ...inspectorState, decisionPageStatus: "loading" };
+    const isCurrent = () =>
+      this.inspectorEpoch === epoch &&
+      this.context.gateway === gateway &&
+      gateway.snapshot.client === client &&
+      gateway.snapshot.phase === "connected" &&
+      inspectorRequestKey(this.routeData) === requestSelectorKey;
+    const params =
+      selector.kind === "run"
+        ? { runId: selector.id, decisionCursor: cursor, decisionLimit: 50, executionLimit: 50 }
+        : { executionId: selector.id, decisionCursor: cursor, decisionLimit: 50 };
+    void client
+      .request<AuditRunInspectResult>("audit.run.inspect", params, { signal: abort.signal })
+      .then((page) => {
+        if (!isCurrent()) {
+          return;
+        }
+        const result = mergeDecisionPage(inspectorState.result, page);
+        if (!result) {
+          this.runInspector = { ...inspectorState, decisionPageStatus: "error" };
+          return;
+        }
+        const cursors = new Map(inspectorState.receiptPageCursors);
+        for (const receipt of page.decisionDisplays) {
+          cursors.set(receipt.selectorId, cursor);
+        }
+        this.runInspector = { status: "ready", result, receiptPageCursors: cursors };
+      })
+      .catch((error: unknown) => {
+        if (!isCurrent() || abort.signal.aborted) {
+          return;
+        }
+        this.runInspector = isMissingOperatorReadScopeError(error)
+          ? { status: "unauthorized" }
+          : this.isUnknownInspectMethod(error)
+            ? { status: "unsupported" }
+            : { ...inspectorState, decisionPageStatus: "error" };
+      })
+      .finally(() => {
+        if (this.inspectorAbort === abort) {
+          this.inspectorAbort = null;
+        }
+      });
+  }
+
+  private restartRunInspector() {
+    const route = this.routeData;
+    if (route.mode !== "run" || !route.selector) {
+      return;
+    }
+    this.context.navigate("activity", { search: activityRunInspectorSearch(route.selector) });
+  }
+
   private selectMode(mode: "sessions" | "live") {
     if (mode === "sessions") {
       this.context.navigate("activity", { search: "" });
@@ -547,6 +662,10 @@ class ActivityPage extends OpenClawLightDomElement {
                   basePath: this.context.basePath,
                   state: this.runInspector,
                   onLoadMoreExecutions: () => this.loadMoreExecutions(),
+                  onLoadMoreDecisions: () => this.loadMoreDecisions(),
+                  selectorId: this.routeData.mode === "run" ? this.routeData.selectorId : null,
+                  selector: this.routeData.mode === "run" ? this.routeData.selector : null,
+                  onRestart: () => this.restartRunInspector(),
                   onRetry: () =>
                     this.syncRunInspector(
                       this.context.gateway,
diff --git a/ui/src/pages/activity/route.test.ts b/ui/src/pages/activity/route.test.ts
index a307fa65e741..f8ef9ba50f36 100644
--- a/ui/src/pages/activity/route.test.ts
+++ b/ui/src/pages/activity/route.test.ts
@@ -49,6 +49,8 @@ describe("resolveActivityRouteData", () => {
     expect(loadRoute(`?view=run&run=${encodeURIComponent(runId)}`)).toEqual({
       mode: "run",
       selector: { kind: "run", id: runId },
+      selectorId: null,
+      decisionCursor: null,
     });
   });
 
@@ -59,14 +61,40 @@ describe("resolveActivityRouteData", () => {
     ).toEqual({
       mode: "run",
       selector: { kind: "execution", id: executionId },
+      selectorId: null,
+      decisionCursor: null,
+    });
+  });
+
+  it("preserves an encoded receipt deep link only with its selected page", () => {
+    expect(
+      loadRoute("?view=run&run=run-1&receipt=receipt%3Aa%2Fb&decision=cursor%3A10%3A2"),
+    ).toEqual({
+      mode: "run",
+      selector: { kind: "run", id: "run-1" },
+      selectorId: "receipt:a/b",
+      decisionCursor: "cursor:10:2",
+    });
+    expect(loadRoute("?view=run&run=run-1&decision=ignored-without-receipt")).toEqual({
+      mode: "run",
+      selector: { kind: "run", id: "run-1" },
+      selectorId: null,
+      decisionCursor: null,
     });
   });
 
   it("keeps a run view with an empty selection explicit", () => {
-    expect(loadRoute("?view=run")).toEqual({ mode: "run", selector: null });
+    expect(loadRoute("?view=run")).toEqual({
+      mode: "run",
+      selector: null,
+      selectorId: null,
+      decisionCursor: null,
+    });
     expect(loadRoute("?view=run&run=%20%20")).toEqual({
       mode: "run",
       selector: null,
+      selectorId: null,
+      decisionCursor: null,
     });
   });
 });
diff --git a/ui/src/pages/activity/run-inspector-evidence-view.ts b/ui/src/pages/activity/run-inspector-evidence-view.ts
new file mode 100644
index 000000000000..dc4d1871f4a3
--- /dev/null
+++ b/ui/src/pages/activity/run-inspector-evidence-view.ts
@@ -0,0 +1,331 @@
+import { html, nothing, type TemplateResult } from "lit";
+import type {
+  AuditRunInspectResult,
+  DecisionReceiptDisplayV1,
+} from "../../../../packages/gateway-protocol/src/schema/audit-run.js";
+import { t } from "../../i18n/index.ts";
+import {
+  activityRunInspectorSelectorHref,
+  type RunInspectorSelector,
+  type RunInspectorState,
+} from "./run-inspector-model.ts";
+
+type ReceiptSectionOptions = { headingId?: string; headingLevel?: 3 | 6 };
+
+export function runInspectorCoverageKey(
+  state: AuditRunInspectResult["coverage"]["state"],
+): "enforced" | "attributionOnly" | "unattributed" | "unknown" | "unsupported" {
+  return state === "attribution-only" ? "attributionOnly" : state;
+}
+
+export function runInspectorCoverageLabel(
+  state: AuditRunInspectResult["coverage"]["state"],
+): string {
+  return t(`activity.runInspector.coverage.${runInspectorCoverageKey(state)}.label`);
+}
+
+export function renderRunInspectorSafeRef(value: string | number, mono = false, href?: string) {
+  const content = html`<bdi
+    class=${mono ? "run-inspector__ref mono" : "run-inspector__ref"}
+    dir="ltr"
+    >${value}</bdi
+  >`;
+  return href ? html`<a href=${href}>${content}</a>` : content;
+}
+
+function renderSectionHeading(label: string, headingId: string, headingLevel: 3 | 6) {
+  return headingLevel === 6
+    ? html`<h6 id=${headingId}>${label}</h6>`
+    : html`<h3 id=${headingId}>${label}</h3>`;
+}
+
+export function renderRunInspectorMissingEvidence(
+  values: readonly string[],
+  options: ReceiptSectionOptions = {},
+) {
+  const headingId = options.headingId ?? "run-inspector-missing-heading";
+  return html`
+    <section class="run-inspector__section" aria-labelledby=${headingId}>
+      ${renderSectionHeading(
+        t("activity.runInspector.missingEvidenceHeading"),
+        headingId,
+        options.headingLevel ?? 3,
+      )}
+      ${values.length === 0
+        ? html`<p>${t("activity.runInspector.noMissingEvidence")}</p>`
+        : html`<ul class="run-inspector__code-list">
+            ${values.map((value) => html`<li>${renderRunInspectorSafeRef(value, true)}</li>`)}
+          </ul>`}
+    </section>
+  `;
+}
+
+export function renderRunInspectorRemediation(
+  remediation: readonly { code: string; text: string }[],
+  options: ReceiptSectionOptions = {},
+): TemplateResult | typeof nothing {
+  if (remediation.length === 0) {
+    return nothing;
+  }
+  const headingId = options.headingId ?? "run-inspector-remediation-heading";
+  return html`
+    <section class="run-inspector__section" aria-labelledby=${headingId}>
+      ${renderSectionHeading(
+        t("activity.runInspector.nextStepsHeading"),
+        headingId,
+        options.headingLevel ?? 3,
+      )}
+      <ul class="run-inspector__remediation-list">
+        ${remediation.map(
+          (item) => html`<li>
+            <span>${item.text}</span> ${renderRunInspectorSafeRef(item.code, true)}
+          </li>`,
+        )}
+      </ul>
+    </section>
+  `;
+}
+
+function receiptInspectorHref(
+  selector: RunInspectorSelector,
+  selectorId: string,
+  decisionCursor: string | undefined,
+  basePath: string,
+): string {
+  return activityRunInspectorSelectorHref(selector, basePath, {
+    id: selectorId,
+    decisionCursor,
+  });
+}
+
+function decisionOutcomeLabel(outcome: DecisionReceiptDisplayV1["decision"]["outcome"]): string {
+  return t(
+    `activity.runInspector.decisions.outcomes.${outcome === "not-applicable" ? "notApplicable" : outcome}`,
+  );
+}
+
+function renderReceiptCodes(values: readonly string[], emptyCopy: string) {
+  return values.length === 0
+    ? html`<p class="run-inspector__reason">${emptyCopy}</p>`
+    : html`<ul class="run-inspector__code-list">
+        ${values.map((value) => html`<li>${renderRunInspectorSafeRef(value, true)}</li>`)}
+      </ul>`;
+}
+
+function renderReceiptDetail(receipt: DecisionReceiptDisplayV1) {
+  const coverage = receipt.enforcement.coverageState;
+  return html`
+    <article class="run-inspector__receipt-detail" aria-labelledby="run-inspector-receipt-detail">
+      <h4 id="run-inspector-receipt-detail">
+        ${t("activity.runInspector.decisions.detailHeading")}
+      </h4>
+      <section aria-labelledby="run-inspector-receipt-requested">
+        <h5 id="run-inspector-receipt-requested">
+          ${t("activity.runInspector.decisions.requestedHeading")}
+        </h5>
+        ${receipt.action.summary ? html`<p>${receipt.action.summary}</p>` : nothing}
+        <dl class="run-inspector__values">
+          <div>
+            <dt>${t("activity.runInspector.values.kind")}</dt>
+            <dd>${renderRunInspectorSafeRef(receipt.action.family)}</dd>
+          </div>
+          <div>
+            <dt>${t("activity.runInspector.values.operation")}</dt>
+            <dd>${renderRunInspectorSafeRef(receipt.action.operation)}</dd>
+          </div>
+        </dl>
+      </section>
+      <section aria-labelledby="run-inspector-receipt-outcome">
+        <h5 id="run-inspector-receipt-outcome">
+          ${t("activity.runInspector.decisions.outcomeHeading")}
+        </h5>
+        <div class="run-inspector__receipt-badges">
+          <span
+            class="run-inspector__receipt-badge run-inspector__receipt-badge--${receipt.decision
+              .outcome}"
+            aria-label=${`${t("activity.runInspector.decisions.outcomeLabel")}: ${decisionOutcomeLabel(
+              receipt.decision.outcome,
+            )}`}
+          >
+            ${decisionOutcomeLabel(receipt.decision.outcome)}
+          </span>
+          <span
+            class="run-inspector__receipt-badge run-inspector__receipt-badge--${coverage}"
+            aria-label=${`${t("activity.runInspector.decisions.classificationLabel")}: ${runInspectorCoverageLabel(
+              coverage,
+            )}`}
+          >
+            ${runInspectorCoverageLabel(coverage)}
+          </span>
+        </div>
+        <p class="run-inspector__reason">
+          ${t(`activity.runInspector.coverage.${runInspectorCoverageKey(coverage)}.description`)}
+        </p>
+        <dl class="run-inspector__values">
+          <div>
+            <dt>${t("activity.runInspector.decisions.reasonLabel")}</dt>
+            <dd>${renderRunInspectorSafeRef(receipt.decision.reasonCode, true)}</dd>
+          </div>
+          <div>
+            <dt>${t("activity.runInspector.decisions.occurredAtLabel")}</dt>
+            <dd>${new Date(receipt.occurredAt).toLocaleString()}</dd>
+          </div>
+        </dl>
+      </section>
+      <section aria-labelledby="run-inspector-receipt-owner">
+        <h5 id="run-inspector-receipt-owner">
+          ${t("activity.runInspector.decisions.ownerHeading")}
+        </h5>
+        ${receipt.provenance.state === "verified"
+          ? html`<dl class="run-inspector__values">
+                <div>
+                  <dt>${t("activity.runInspector.decisions.durableOwnerLabel")}</dt>
+                  <dd>${renderRunInspectorSafeRef(receipt.provenance.producer)}</dd>
+                </div>
+              </dl>
+              <p class="run-inspector__reason">
+                ${t("activity.runInspector.decisions.ownerNote")}
+              </p>`
+          : html`<p class="run-inspector__reason">
+              ${t("activity.runInspector.decisions.ownerNote")}
+            </p>`}
+      </section>
+      <section aria-labelledby="run-inspector-receipt-evidence">
+        <h5 id="run-inspector-receipt-evidence">
+          ${t("activity.runInspector.decisions.evidenceHeading")}
+        </h5>
+        <dl class="run-inspector__values">
+          <div>
+            <dt>${t("activity.runInspector.decisions.policyCountLabel")}</dt>
+            <dd>${receipt.enforcement.policyCount}</dd>
+          </div>
+          <div>
+            <dt>${t("activity.runInspector.decisions.grantCountLabel")}</dt>
+            <dd>${receipt.enforcement.grantCount}</dd>
+          </div>
+        </dl>
+        <h6>${t("activity.runInspector.decisions.contextFieldsLabel")}</h6>
+        ${renderReceiptCodes(
+          receipt.enforcement.contextFieldsUsed,
+          t("activity.runInspector.decisions.noContextFields"),
+        )}
+        ${renderRunInspectorMissingEvidence(receipt.missingEvidence, {
+          headingId: "run-inspector-receipt-missing-heading",
+          headingLevel: 6,
+        })}
+      </section>
+      ${renderRunInspectorRemediation(receipt.remediation, {
+        headingId: "run-inspector-receipt-remediation-heading",
+        headingLevel: 6,
+      })}
+    </article>
+  `;
+}
+
+export function renderRunInspectorDecisions(
+  state: Extract<RunInspectorState, { status: "ready" }>,
+  selector: RunInspectorSelector | null,
+  selectorId: string | null,
+  basePath: string,
+  onLoadMoreDecisions: () => void,
+) {
+  const result = state.result;
+  const selectedReceipt = selectorId
+    ? result.decisionDisplays.find((receipt) => receipt.selectorId === selectorId)
+    : result.decisionDisplays[0];
+  return html`
+    <section class="run-inspector__section" aria-labelledby="run-inspector-decisions-heading">
+      <h3 id="run-inspector-decisions-heading">${t("activity.runInspector.decisions.heading")}</h3>
+      ${result.decisionDisplays.length === 0
+        ? html`<p>${t("activity.runInspector.decisions.none")}</p>`
+        : html`<p>
+            ${t("activity.runInspector.decisions.returned", {
+              count: String(result.decisionDisplays.length),
+            })}
+          </p>`}
+      <div class="run-inspector__warning" role="note">
+        ${t("activity.runInspector.decisions.readOnly")}
+      </div>
+      ${result.decisionDisplays.length > 0 && selector
+        ? html`<ol
+            class="run-inspector__receipt-list"
+            aria-label=${t("activity.runInspector.decisions.listLabel")}
+          >
+            ${result.decisionDisplays.map((receipt) => {
+              const selected = selectedReceipt?.selectorId === receipt.selectorId;
+              return html`<li>
+                <a
+                  href=${receiptInspectorHref(
+                    selector,
+                    receipt.selectorId,
+                    state.receiptPageCursors.get(receipt.selectorId),
+                    basePath,
+                  )}
+                  aria-current=${selected ? "true" : nothing}
+                  aria-label=${t("activity.runInspector.decisions.inspectLabel", {
+                    summary:
+                      receipt.action.summary ??
+                      `${receipt.action.family} · ${receipt.action.operation}`,
+                    outcome: decisionOutcomeLabel(receipt.decision.outcome),
+                    classification: runInspectorCoverageLabel(receipt.enforcement.coverageState),
+                  })}
+                >
+                  <span
+                    >${receipt.action.summary ??
+                    `${receipt.action.family} · ${receipt.action.operation}`}</span
+                  >
+                  <span class="run-inspector__receipt-badges" aria-hidden="true">
+                    <span
+                      class="run-inspector__receipt-badge run-inspector__receipt-badge--${receipt
+                        .decision.outcome}"
+                      >${decisionOutcomeLabel(receipt.decision.outcome)}</span
+                    >
+                    <span
+                      class="run-inspector__receipt-badge run-inspector__receipt-badge--${receipt
+                        .enforcement.coverageState}"
+                      >${runInspectorCoverageLabel(receipt.enforcement.coverageState)}</span
+                    >
+                  </span>
+                </a>
+              </li>`;
+            })}
+          </ol>`
+        : nothing}
+      ${result.nextDecisionCursor
+        ? html`<div class="run-inspector__pagination">
+            <span>${t("activity.runInspector.decisions.more")}</span>
+            <button
+              type="button"
+              class="btn"
+              ?disabled=${state.decisionPageStatus === "loading"}
+              @click=${onLoadMoreDecisions}
+            >
+              ${state.decisionPageStatus === "loading"
+                ? t("activity.runInspector.decisions.loadingMore")
+                : t("activity.runInspector.decisions.loadMore")}
+            </button>
+            ${state.decisionPageStatus === "error"
+              ? html`<span role="alert">
+                  ${t("activity.runInspector.decisions.loadMoreError")}
+                </span>`
+              : nothing}
+          </div>`
+        : html`<div class="run-inspector__pagination" role="note">
+            ${t("activity.runInspector.decisions.bounded")}
+          </div>`}
+      ${selectorId && !selectedReceipt
+        ? html`<div class="run-inspector__result-state" role="status">
+            <h4>${t("activity.runInspector.decisions.notFoundTitle")}</h4>
+            <p>${t("activity.runInspector.decisions.notFoundDescription")}</p>
+            ${selector
+              ? html`<a href=${activityRunInspectorSelectorHref(selector, basePath)}>
+                  ${t("activity.runInspector.decisions.heading")}
+                </a>`
+              : nothing}
+          </div>`
+        : selectedReceipt
+          ? renderReceiptDetail(selectedReceipt)
+          : nothing}
+    </section>
+  `;
+}
diff --git a/ui/src/pages/activity/run-inspector-model.test.ts b/ui/src/pages/activity/run-inspector-model.test.ts
index 84439f3f3f39..1a7422ece720 100644
--- a/ui/src/pages/activity/run-inspector-model.test.ts
+++ b/ui/src/pages/activity/run-inspector-model.test.ts
@@ -1,13 +1,16 @@
 import { describe, expect, it } from "vitest";
 // @vitest-environment node
-import type { AuditRunInspectResult } from "../../../../packages/gateway-protocol/src/schema/audit-run.js";
-import { classifyRunInspection } from "./run-inspector-model.ts";
+import {
+  classifyRunInspection,
+  mergeDecisionPage,
+  type RunInspectorResult,
+} from "./run-inspector-model.ts";
 
 function unavailable(
   state: "unknown" | "unsupported" | "ambiguous",
   reasonCode: string,
   remediation: Array<{ code: string; text: string }> = [],
-): AuditRunInspectResult {
+): RunInspectorResult {
   return {
     schemaVersion: 1,
     run: { runId: "run-1", status: state === "unknown" ? "unknown" : "known" },
@@ -26,7 +29,7 @@ function unavailable(
             missingEvidence: ["identity.context"],
             remediation,
           },
-    decisions: [],
+    decisionDisplays: [],
     coverage: { state: state === "ambiguous" ? "unknown" : state, missingEvidence: [] },
   };
 }
@@ -48,3 +51,63 @@ describe("classifyRunInspection", () => {
     expect(classifyRunInspection(result)).toBe(expected);
   });
 });
+
+describe("receipt paging model", () => {
+  const present = {
+    schemaVersion: 1,
+    run: {
+      runId: "run-1",
+      executionId: "execution-1",
+      status: "known" as const,
+    },
+    identity: {
+      state: "present" as const,
+      context: {
+        schemaVersion: 1,
+        contextId: "context-1",
+        executionId: "execution-1",
+        runId: "run-1",
+        createdAt: 1,
+        trustDomain: {
+          kind: "gateway-cell" as const,
+          domainRef: "domain",
+          state: "present" as const,
+        },
+        invoker: { state: "absent" as const },
+        ingress: {
+          kind: "gateway-client" as const,
+          boundary: "agent-command.gateway",
+          state: "present" as const,
+        },
+        agentPrincipal: {
+          kind: "agent" as const,
+          domainRef: "domain",
+          principalRef: "main",
+        },
+        agentDefinition: { definitionRef: "main", state: "unknown" as const },
+        runtimeInstance: {
+          runtimeRef: "gateway",
+          kind: "gateway" as const,
+          state: "present" as const,
+        },
+        applicableGrants: [],
+        assurance: [],
+        coverageState: "attribution-only" as const,
+        missingEvidence: [],
+      },
+    },
+    decisionDisplays: [],
+    coverage: { state: "attribution-only" as const, missingEvidence: [] },
+  } satisfies RunInspectorResult;
+
+  it("merges only a page for the exact inspected execution and context", () => {
+    const page = { ...present, nextDecisionCursor: "g:10:2" };
+    expect(mergeDecisionPage(present, page)?.nextDecisionCursor).toBe("g:10:2");
+    expect(
+      mergeDecisionPage(present, {
+        ...page,
+        run: { ...page.run, executionId: "execution-2" },
+      }),
+    ).toBeNull();
+  });
+});
diff --git a/ui/src/pages/activity/run-inspector-model.ts b/ui/src/pages/activity/run-inspector-model.ts
index aad3ab61b215..960f7ba2577c 100644
--- a/ui/src/pages/activity/run-inspector-model.ts
+++ b/ui/src/pages/activity/run-inspector-model.ts
@@ -1,4 +1,7 @@
-import type { AuditRunInspectResult } from "../../../../packages/gateway-protocol/src/schema/audit-run.js";
+import type {
+  AuditRunInspectResult,
+  DecisionReceiptDisplayV1,
+} from "../../../../packages/gateway-protocol/src/schema/audit-run.js";
 import { pathForRoute } from "../../app-route-paths.ts";
 import { parseSessionActivityFilters, type SessionActivityFilters } from "./session-activity.ts";
 
@@ -7,10 +10,37 @@ export type RunInspectorSelector = { kind: "run" | "execution"; id: string };
 export type ActivityRouteData =
   | { mode: "sessions"; filters: SessionActivityFilters; selector: null }
   | { mode: "live"; selector: null }
-  | { mode: "run"; selector: RunInspectorSelector | null };
+  | {
+      mode: "run";
+      selector: RunInspectorSelector | null;
+      selectorId: string | null;
+      decisionCursor: string | null;
+    };
+
+export function activityRunInspectorSearch(
+  selector: RunInspectorSelector,
+  receipt?: { id: string; decisionCursor?: string },
+): string {
+  let search = `?view=run&${selector.kind}=${encodeURIComponent(selector.id)}`;
+  if (receipt) {
+    search += `&receipt=${encodeURIComponent(receipt.id)}`;
+    if (receipt.decisionCursor) {
+      search += `&decision=${encodeURIComponent(receipt.decisionCursor)}`;
+    }
+  }
+  return search;
+}
+
+export function activityRunInspectorSelectorHref(
+  selector: RunInspectorSelector,
+  basePath: string,
+  receipt?: { id: string; decisionCursor?: string },
+): string {
+  return `${pathForRoute("activity", basePath)}${activityRunInspectorSearch(selector, receipt)}`;
+}
 
 export function activityRunInspectorHref(runId: string, basePath: string): string {
-  return `${pathForRoute("activity", basePath)}?view=run&run=${encodeURIComponent(runId)}`;
+  return activityRunInspectorSelectorHref({ kind: "run", id: runId }, basePath);
 }
 
 export function resolveActivityRouteData(search: string): ActivityRouteData {
@@ -22,29 +52,75 @@ export function resolveActivityRouteData(search: string): ActivityRouteData {
     return { mode: "sessions", filters: parseSessionActivityFilters(search), selector: null };
   }
   const executionId = params.get("execution");
+  const selectorId = params.get("receipt")?.trim() || null;
+  const decisionCursor = selectorId ? params.get("decision")?.trim() || null : null;
   if (executionId?.trim()) {
-    return { mode: "run", selector: { kind: "execution", id: executionId } };
+    return {
+      mode: "run",
+      selector: { kind: "execution", id: executionId },
+      selectorId,
+      decisionCursor,
+    };
   }
   const runId = params.get("run");
   return {
     mode: "run",
     selector: runId?.trim() ? { kind: "run", id: runId } : null,
+    selectorId,
+    decisionCursor,
   };
 }
 
+type ReceiptPageCursorMap = ReadonlyMap<string, string | undefined>;
+
+export type RunInspectorResult = AuditRunInspectResult;
+
 export type RunInspectorState =
   | { status: "empty" }
   | { status: "loading"; waitingForGateway: boolean }
   | { status: "disconnected" }
   | { status: "unauthorized" }
   | { status: "unsupported" }
-  | { status: "error" }
+  | { status: "error"; recovery: "restart" | "retry" }
   | {
       status: "ready";
-      result: AuditRunInspectResult;
+      result: RunInspectorResult;
       executionPageStatus?: "loading" | "error";
+      decisionPageStatus?: "loading" | "error";
+      receiptPageCursors: ReceiptPageCursorMap;
     };
 
+export function receiptPageCursors(
+  receipts: readonly DecisionReceiptDisplayV1[],
+  cursor?: string,
+): ReceiptPageCursorMap {
+  return new Map(receipts.map((receipt) => [receipt.selectorId, cursor]));
+}
+
+export function mergeDecisionPage(
+  previous: RunInspectorResult,
+  page: RunInspectorResult,
+): RunInspectorResult | null {
+  if (
+    previous.identity.state !== "present" ||
+    page.identity.state !== "present" ||
+    previous.run.executionId !== page.run.executionId ||
+    previous.identity.context.contextId !== page.identity.context.contextId
+  ) {
+    return null;
+  }
+  const decisions = new Map(
+    previous.decisionDisplays.map((receipt) => [receipt.selectorId, receipt]),
+  );
+  for (const receipt of page.decisionDisplays) {
+    decisions.set(receipt.selectorId, receipt);
+  }
+  return {
+    ...page,
+    decisionDisplays: [...decisions.values()],
+  };
+}
+
 type RunInspectorDiagnosticKind =
   | "present"
   | "not-found"
@@ -54,7 +130,7 @@ type RunInspectorDiagnosticKind =
   | "unknown"
   | "unsupported";
 
-export function classifyRunInspection(result: AuditRunInspectResult): RunInspectorDiagnosticKind {
+export function classifyRunInspection(result: RunInspectorResult): RunInspectorDiagnosticKind {
   const identity = result.identity;
   if (identity.state === "present") {
     return "present";
diff --git a/ui/src/pages/activity/run-inspector-view.test.ts b/ui/src/pages/activity/run-inspector-view.test.ts
index 12770593c135..1357c9bd1574 100644
--- a/ui/src/pages/activity/run-inspector-view.test.ts
+++ b/ui/src/pages/activity/run-inspector-view.test.ts
@@ -2,13 +2,13 @@
 
 import { render } from "lit";
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { AuditRunInspectResult } from "../../../../packages/gateway-protocol/src/schema/audit-run.js";
-import type { RunInspectorState } from "./run-inspector-model.ts";
+import { t } from "../../i18n/index.ts";
+import type { RunInspectorResult, RunInspectorState } from "./run-inspector-model.ts";
 import { renderRunInspector } from "./run-inspector-view.ts";
 
 const hmacRef = `hmac-sha256:v1:${"a".repeat(32)}:${"b".repeat(64)}`;
 
-function presentResult(): AuditRunInspectResult {
+function presentResult(): RunInspectorResult {
   return {
     schemaVersion: 1,
     run: { runId: "run-1", executionId: "execution-1", status: "known" },
@@ -53,13 +53,10 @@ function presentResult(): AuditRunInspectResult {
         missingEvidence: ["invoker.principal"],
       },
     },
-    decisions: [
+    decisionDisplays: [
       {
         schemaVersion: 1,
-        receiptId: "receipt-1",
-        contextId: "context-1",
-        executionId: "execution-1",
-        runId: "run-1",
+        selectorId: "receipt-1",
         occurredAt: 1,
         action: {
           family: "run",
@@ -69,15 +66,11 @@ function presentResult(): AuditRunInspectResult {
         decision: { outcome: "not-applicable", reasonCode: "identity_not_evaluated" },
         enforcement: {
           coverageState: "unattributed",
-          policyRefs: [],
-          grantRefs: [],
+          policyCount: 0,
+          grantCount: 0,
           contextFieldsUsed: [],
         },
-        source: {
-          owner: "agent-command",
-          recordRef: "context-1",
-          decisionBoundary: "agent-command.run-admission",
-        },
+        provenance: { state: "verified", producer: "run-admission" },
         missingEvidence: ["invoker.principal"],
         remediation: [
           { code: "no_identity_enforcement_claimed", text: "Do not treat this as authorization." },
@@ -93,7 +86,7 @@ function unavailableResult(
   state: "unknown" | "unsupported",
   reasonCode: string,
   remediation: Array<{ code: string; text: string }> = [],
-): AuditRunInspectResult {
+): RunInspectorResult {
   return {
     schemaVersion: 1,
     run: { runId: "run-1", status: state === "unknown" ? "unknown" : "known" },
@@ -103,19 +96,40 @@ function unavailableResult(
       missingEvidence: ["identity.context"],
       remediation,
     },
-    decisions: [],
+    decisionDisplays: [],
     coverage: { state, missingEvidence: ["identity.context"] },
   };
 }
 
-function renderState(state: RunInspectorState, onLoadMoreExecutions = vi.fn()) {
+type ViewTestState =
+  | Exclude<RunInspectorState, { status: "ready" }>
+  | (Omit<Extract<RunInspectorState, { status: "ready" }>, "receiptPageCursors"> & {
+      receiptPageCursors?: ReadonlyMap<string, string | undefined>;
+    });
+
+function renderState(state: ViewTestState, onLoadMoreExecutions = vi.fn()) {
   const container = document.createElement("div");
   document.body.append(container);
+  const normalizedState: RunInspectorState =
+    state.status === "ready"
+      ? {
+          ...state,
+          receiptPageCursors:
+            state.receiptPageCursors ??
+            new Map(
+              state.result.decisionDisplays.map((receipt) => [receipt.selectorId, undefined]),
+            ),
+        }
+      : state;
   render(
     renderRunInspector({
       basePath: "/operator",
-      state,
+      state: normalizedState,
+      selector: { kind: "run", id: "run-1" },
+      selectorId: null,
+      onLoadMoreDecisions: vi.fn(),
       onLoadMoreExecutions,
+      onRestart: vi.fn(),
       onRetry: vi.fn(),
     }),
     container,
@@ -159,6 +173,12 @@ describe("renderRunInspector", () => {
     expect(text).not.toContain("context-1");
     expect(text).not.toContain("execution-1");
     expect(text).toContain("Additional decision receipts are available");
+    expect(text).toContain("Not applicable");
+    expect(text).toContain("Unattributed");
+    expect(text).toContain("identity_not_evaluated");
+    expect(text).toContain("Verified producer");
+    expect(text).toContain("run-admission");
+    expect(text).toContain("Do not treat this as authorization.");
     expect(text).toContain("Best-effort audit warning");
     expect(text).not.toContain("raw-sender-id-42");
     expect(
@@ -179,11 +199,18 @@ describe("renderRunInspector", () => {
     [{ status: "disconnected" } satisfies RunInspectorState, "Gateway disconnected"],
     [{ status: "unauthorized" } satisfies RunInspectorState, "Operator read access required"],
     [{ status: "unsupported" } satisfies RunInspectorState, "Run inspection unsupported"],
-    [{ status: "error" } satisfies RunInspectorState, "Run inspection failed"],
+    [{ status: "error", recovery: "retry" } satisfies RunInspectorState, "Run inspection failed"],
   ])("renders the explicit panel state", (state, expected) => {
     expect(renderState(state).textContent).toContain(expected);
   });
 
+  it("renders the localized restart control with its accessible name", () => {
+    expect(t("activity.runInspector.restart")).toBe("Restart inspection");
+
+    const button = renderState({ status: "error", recovery: "restart" }).querySelector("button");
+    expect(button?.textContent?.trim()).toBe("Restart inspection");
+  });
+
   it.each([
     [unavailableResult("unknown", "run_not_found"), "Run not found"],
     [
@@ -202,7 +229,7 @@ describe("renderRunInspector", () => {
   });
 
   it("links an ambiguous run candidate to exact execution inspection", () => {
-    const result: AuditRunInspectResult = {
+    const result: RunInspectorResult = {
       schemaVersion: 1,
       run: { runId: "ambiguous-run", status: "known" },
       identity: {
@@ -214,7 +241,7 @@ describe("renderRunInspector", () => {
         missingEvidence: ["execution.selection"],
         remediation: [],
       },
-      decisions: [],
+      decisionDisplays: [],
       coverage: { state: "unknown", missingEvidence: ["execution.selection"] },
       nextExecutionCursor: "opaque-cursor",
     };
diff --git a/ui/src/pages/activity/run-inspector-view.ts b/ui/src/pages/activity/run-inspector-view.ts
index 25e21a312007..e45711735363 100644
--- a/ui/src/pages/activity/run-inspector-view.ts
+++ b/ui/src/pages/activity/run-inspector-view.ts
@@ -1,13 +1,25 @@
 import { html, nothing, type TemplateResult } from "lit";
 import type {
-  AuditRunInspectResult,
   ExecutionIdentityContextV1,
   PrincipalRefV1,
 } from "../../../../packages/gateway-protocol/src/schema/audit-run.js";
-import { pathForRoute } from "../../app-route-paths.ts";
 import { t } from "../../i18n/index.ts";
 import { registerActivityEnglish } from "../../i18n/locales/en-activity.ts";
-import { classifyRunInspection, type RunInspectorState } from "./run-inspector-model.ts";
+import {
+  renderRunInspectorDecisions,
+  renderRunInspectorMissingEvidence,
+  renderRunInspectorRemediation,
+  renderRunInspectorSafeRef,
+  runInspectorCoverageKey,
+  runInspectorCoverageLabel,
+} from "./run-inspector-evidence-view.ts";
+import {
+  activityRunInspectorSelectorHref,
+  classifyRunInspection,
+  type RunInspectorResult,
+  type RunInspectorSelector,
+  type RunInspectorState,
+} from "./run-inspector-model.ts";
 import "./run-inspector.css";
 
 registerActivityEnglish();
@@ -17,7 +29,11 @@ type EvidenceState = "present" | "absent" | "unknown" | "unsupported";
 type RunInspectorProps = {
   basePath: string;
   state: RunInspectorState;
+  selector: RunInspectorSelector | null;
+  selectorId: string | null;
+  onLoadMoreDecisions: () => void;
   onLoadMoreExecutions: () => void;
+  onRestart: () => void;
   onRetry: () => void;
 };
 
@@ -39,25 +55,6 @@ function evidenceStateLabel(state: EvidenceState): string {
   return t(`activity.runInspector.evidenceState.${state}`);
 }
 
-function coverageKey(
-  state: AuditRunInspectResult["coverage"]["state"],
-): "enforced" | "attributionOnly" | "unattributed" | "unknown" | "unsupported" {
-  return state === "attribution-only" ? "attributionOnly" : state;
-}
-
-function coverageLabel(state: AuditRunInspectResult["coverage"]["state"]): string {
-  return t(`activity.runInspector.coverage.${coverageKey(state)}.label`);
-}
-
-function renderSafeRef(value: string | number, mono = false, href?: string) {
-  const content = html`<bdi
-    class=${mono ? "run-inspector__ref mono" : "run-inspector__ref"}
-    dir="ltr"
-    >${value}</bdi
-  >`;
-  return href ? html`<a href=${href}>${content}</a>` : content;
-}
-
 function stateReason(label: string, state: EvidenceState): string | undefined {
   switch (state) {
     case "absent":
@@ -118,7 +115,7 @@ function renderFact(fact: IdentityFact) {
                 (item) => html`
                   <div>
                     <dt>${item.label}</dt>
-                    <dd>${renderSafeRef(item.value, item.mono, item.href)}</dd>
+                    <dd>${renderRunInspectorSafeRef(item.value, item.mono, item.href)}</dd>
                   </div>
                 `,
               )}
@@ -130,16 +127,6 @@ function renderFact(fact: IdentityFact) {
   `;
 }
 
-function runInspectorHref(runId: string, basePath: string): string {
-  const search = new URLSearchParams({ view: "run", run: runId });
-  return `${pathForRoute("activity", basePath)}?${search.toString()}`;
-}
-
-function executionInspectorHref(executionId: string, basePath: string): string {
-  const search = new URLSearchParams({ view: "run", execution: executionId });
-  return `${pathForRoute("activity", basePath)}?${search.toString()}`;
-}
-
 function identityFacts(context: ExecutionIdentityContextV1, basePath: string): IdentityFact[] {
   const representedSubject = context.representedSubject;
   const sponsor = context.sponsor;
@@ -299,7 +286,10 @@ function identityFacts(context: ExecutionIdentityContextV1, basePath: string): I
                     label: t("activity.runInspector.values.parentRunReference"),
                     value: lineage.parentRunId,
                     mono: true,
-                    href: runInspectorHref(lineage.parentRunId, basePath),
+                    href: activityRunInspectorSelectorHref(
+                      { kind: "run", id: lineage.parentRunId },
+                      basePath,
+                    ),
                   },
                 ]
               : []),
@@ -338,65 +328,7 @@ function identityFacts(context: ExecutionIdentityContextV1, basePath: string): I
   ];
 }
 
-function renderMissingEvidence(values: readonly string[]) {
-  return html`
-    <section class="run-inspector__section" aria-labelledby="run-inspector-missing-heading">
-      <h3 id="run-inspector-missing-heading">
-        ${t("activity.runInspector.missingEvidenceHeading")}
-      </h3>
-      ${values.length === 0
-        ? html`<p>${t("activity.runInspector.noMissingEvidence")}</p>`
-        : html`<ul class="run-inspector__code-list">
-            ${values.map((value) => html`<li>${renderSafeRef(value, true)}</li>`)}
-          </ul>`}
-    </section>
-  `;
-}
-
-function renderRemediation(
-  remediation: readonly { code: string; text: string }[],
-): TemplateResult | typeof nothing {
-  if (remediation.length === 0) {
-    return nothing;
-  }
-  return html`
-    <section
-      class="run-inspector__section"
-      aria-label=${t("activity.runInspector.nextStepsHeading")}
-    >
-      <h3>${t("activity.runInspector.nextStepsHeading")}</h3>
-      <ul class="run-inspector__remediation-list">
-        ${remediation.map(
-          (item) => html`<li><span>${item.text}</span> ${renderSafeRef(item.code, true)}</li>`,
-        )}
-      </ul>
-    </section>
-  `;
-}
-
-function renderDecisions(result: AuditRunInspectResult) {
-  return html`
-    <section class="run-inspector__section" aria-labelledby="run-inspector-decisions-heading">
-      <h3 id="run-inspector-decisions-heading">${t("activity.runInspector.decisions.heading")}</h3>
-      ${result.decisions.length === 0
-        ? html`<p>${t("activity.runInspector.decisions.none")}</p>`
-        : html`<p>
-            ${t("activity.runInspector.decisions.returned", {
-              count: String(result.decisions.length),
-            })}
-          </p>`}
-      ${result.nextDecisionCursor
-        ? html`<div class="run-inspector__pagination" role="note">
-            ${t("activity.runInspector.decisions.more")}
-          </div>`
-        : html`<div class="run-inspector__pagination" role="note">
-            ${t("activity.runInspector.decisions.bounded")}
-          </div>`}
-    </section>
-  `;
-}
-
-function diagnosticCopy(result: AuditRunInspectResult) {
+function diagnosticCopy(result: RunInspectorResult) {
   const kind = classifyRunInspection(result);
   switch (kind) {
     case "not-found":
@@ -437,7 +369,7 @@ function diagnosticCopy(result: AuditRunInspectResult) {
 }
 
 function renderUnavailableResult(
-  result: AuditRunInspectResult,
+  result: RunInspectorResult,
   basePath: string,
   executionPageStatus: "loading" | "error" | undefined,
   onLoadMoreExecutions: () => void,
@@ -452,7 +384,8 @@ function renderUnavailableResult(
       <h3>${copy.title}</h3>
       <p>${copy.description}</p>
       <p>
-        ${t("activity.runInspector.diagnosticReason")} ${renderSafeRef(identity.reasonCode, true)}
+        ${t("activity.runInspector.diagnosticReason")}
+        ${renderRunInspectorSafeRef(identity.reasonCode, true)}
       </p>
     </div>
     ${identity.state === "ambiguous"
@@ -469,9 +402,14 @@ function renderUnavailableResult(
                       date: new Date(candidate.createdAt).toLocaleString(),
                     })}</span
                   >
-                  <a href=${executionInspectorHref(candidate.executionId, basePath)}>
+                  <a
+                    href=${activityRunInspectorSelectorHref(
+                      { kind: "execution", id: candidate.executionId },
+                      basePath,
+                    )}
+                  >
                     ${t("activity.runInspector.candidates.executionReference")}
-                    ${renderSafeRef(candidate.executionId, true)}
+                    ${renderRunInspectorSafeRef(candidate.executionId, true)}
                   </a>
                 </li>
               `,
@@ -499,17 +437,21 @@ function renderUnavailableResult(
             : nothing}
         `
       : nothing}
-    ${renderMissingEvidence(identity.missingEvidence)} ${renderRemediation(identity.remediation)}
+    ${renderRunInspectorMissingEvidence(identity.missingEvidence)}
+    ${renderRunInspectorRemediation(identity.remediation)}
   `;
 }
 
 function renderReady(
   state: Extract<RunInspectorState, { status: "ready" }>,
   basePath: string,
+  selector: RunInspectorSelector | null,
+  selectorId: string | null,
+  onLoadMoreDecisions: () => void,
   onLoadMoreExecutions: () => void,
 ) {
   const result = state.result;
-  const currentCoverageLabel = coverageLabel(result.coverage.state);
+  const currentCoverageLabel = runInspectorCoverageLabel(result.coverage.state);
   return html`
     <div
       class="run-inspector__coverage run-inspector__coverage--${result.coverage.state}"
@@ -520,7 +462,9 @@ function renderReady(
     >
       <strong>${currentCoverageLabel}</strong>
       <span>
-        ${t(`activity.runInspector.coverage.${coverageKey(result.coverage.state)}.description`)}
+        ${t(
+          `activity.runInspector.coverage.${runInspectorCoverageKey(result.coverage.state)}.description`,
+        )}
       </span>
     </div>
     ${result.identity.state === "present"
@@ -533,7 +477,8 @@ function renderReady(
               ${identityFacts(result.identity.context, basePath).map(renderFact)}
             </dl>
           </section>
-          ${renderMissingEvidence(result.coverage.missingEvidence)} ${renderDecisions(result)}
+          ${renderRunInspectorMissingEvidence(result.coverage.missingEvidence)}
+          ${renderRunInspectorDecisions(state, selector, selectorId, basePath, onLoadMoreDecisions)}
         `
       : renderUnavailableResult(result, basePath, state.executionPageStatus, onLoadMoreExecutions)}
   `;
@@ -542,15 +487,18 @@ function renderReady(
 function renderPanel(
   title: string,
   description: string,
-  options: { retry?: boolean; onRetry: () => void; role?: "alert" | "status" },
+  options: {
+    action?: { label: string; onClick: () => void };
+    role?: "alert" | "status";
+  } = {},
 ) {
   return html`
     <div class="run-inspector__panel" role=${options.role ?? "status"}>
       <h3>${title}</h3>
       <p>${description}</p>
-      ${options.retry
-        ? html`<button type="button" class="btn" @click=${options.onRetry}>
-            ${t("activity.runInspector.retry")}
+      ${options.action
+        ? html`<button type="button" class="btn" @click=${options.action.onClick}>
+            ${options.action.label}
           </button>`
         : nothing}
     </div>
@@ -565,7 +513,6 @@ export function renderRunInspector(props: RunInspectorProps) {
       content = renderPanel(
         t("activity.runInspector.panels.empty.title"),
         t("activity.runInspector.panels.empty.description"),
-        { onRetry: props.onRetry },
       );
       break;
     case "loading":
@@ -576,39 +523,49 @@ export function renderRunInspector(props: RunInspectorProps) {
         state.waitingForGateway
           ? t("activity.runInspector.panels.waiting.description")
           : t("activity.runInspector.panels.loading.description"),
-        { onRetry: props.onRetry },
       );
       break;
     case "disconnected":
       content = renderPanel(
         t("activity.runInspector.panels.disconnected.title"),
         t("activity.runInspector.panels.disconnected.description"),
-        { onRetry: props.onRetry },
       );
       break;
     case "unauthorized":
       content = renderPanel(
         t("activity.runInspector.panels.unauthorized.title"),
         t("activity.runInspector.panels.unauthorized.description"),
-        { onRetry: props.onRetry, role: "alert" },
+        { role: "alert" },
       );
       break;
     case "unsupported":
       content = renderPanel(
         t("activity.runInspector.panels.unsupported.title"),
         t("activity.runInspector.panels.unsupported.description"),
-        { onRetry: props.onRetry },
       );
       break;
     case "error":
       content = renderPanel(
         t("activity.runInspector.panels.error.title"),
         t("activity.runInspector.panels.error.description"),
-        { onRetry: props.onRetry, retry: true, role: "alert" },
+        {
+          action:
+            state.recovery === "restart"
+              ? { label: t("activity.runInspector.restart"), onClick: props.onRestart }
+              : { label: t("activity.runInspector.retry"), onClick: props.onRetry },
+          role: "alert",
+        },
       );
       break;
     case "ready":
-      content = renderReady(state, props.basePath, props.onLoadMoreExecutions);
+      content = renderReady(
+        state,
+        props.basePath,
+        props.selector,
+        props.selectorId,
+        props.onLoadMoreDecisions,
+        props.onLoadMoreExecutions,
+      );
       break;
   }
 
diff --git a/ui/src/pages/activity/run-inspector.css b/ui/src/pages/activity/run-inspector.css
index f0c9e8e527a4..88b9218a3565 100644
--- a/ui/src/pages/activity/run-inspector.css
+++ b/ui/src/pages/activity/run-inspector.css
@@ -161,7 +161,8 @@
 
 .run-inspector__code-list,
 .run-inspector__remediation-list,
-.run-inspector__candidate-list {
+.run-inspector__candidate-list,
+.run-inspector__receipt-list {
   display: grid;
   gap: var(--space-2);
   margin: 0;
@@ -173,6 +174,83 @@
   gap: var(--space-1);
 }
 
+.run-inspector__receipt-list {
+  list-style: none;
+  padding-left: 0;
+}
+
+.run-inspector__receipt-list a {
+  display: grid;
+  gap: var(--space-2);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: var(--space-3);
+  color: var(--text);
+  text-decoration: none;
+}
+
+.run-inspector__receipt-list a:hover {
+  border-color: color-mix(in srgb, var(--accent) 55%, var(--border));
+}
+
+.run-inspector__receipt-list a:focus-visible {
+  outline: 2px solid var(--focus);
+  outline-offset: 2px;
+}
+
+.run-inspector__receipt-list a[aria-current="true"] {
+  border-color: var(--accent);
+  background: color-mix(in srgb, var(--accent) 8%, transparent);
+}
+
+.run-inspector__receipt-badges {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+}
+
+.run-inspector__receipt-badge {
+  display: inline-flex;
+  width: fit-content;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  padding: 1px var(--space-2);
+  font-size: var(--control-ui-text-xs);
+  font-weight: 600;
+}
+
+.run-inspector__receipt-badge--allowed,
+.run-inspector__receipt-badge--enforced {
+  border-color: color-mix(in srgb, var(--ok) 60%, var(--border));
+}
+
+.run-inspector__receipt-badge--denied,
+.run-inspector__receipt-badge--unknown,
+.run-inspector__receipt-badge--unsupported,
+.run-inspector__receipt-badge--unattributed {
+  border-color: color-mix(in srgb, var(--warn) 60%, var(--border));
+}
+
+.run-inspector__receipt-detail {
+  display: grid;
+  gap: var(--space-4);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: var(--space-4);
+}
+
+.run-inspector__receipt-detail h4,
+.run-inspector__receipt-detail h5,
+.run-inspector__receipt-detail h6,
+.run-inspector__receipt-detail p {
+  margin: 0;
+}
+
+.run-inspector__receipt-detail > section {
+  display: grid;
+  gap: var(--space-2);
+}
+
 @media (max-width: 768px) {
   .run-inspector__fact,
   .run-inspector__values > div {

From cddc1acdf7f9f2d60de89a5b700fb0261a5dcb6a Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 11:33:39 -0700
Subject: [PATCH 059/124] fix(plugins): reuse published metadata on hot paths
 (#127355)

---
 .../read-only-command-defaults.test.ts        | 29 ++++++++++++-
 .../plugins/read-only-command-defaults.ts     |  7 +++-
 src/hooks/plugin-hooks.test.ts                | 25 ++++++++++-
 src/hooks/plugin-hooks.ts                     |  6 +--
 src/plugins/tools.optional.test.ts            | 41 ++++++++++++++++++
 src/plugins/tools.ts                          | 31 +++-----------
 src/secrets/channel-env-vars.dynamic.test.ts  | 42 +++++++++++++++++--
 src/secrets/channel-env-vars.ts               |  6 +--
 src/skills/loading/plugin-skills.test.ts      | 18 ++++++++
 src/skills/loading/plugin-skills.ts           |  3 +-
 10 files changed, 167 insertions(+), 41 deletions(-)

diff --git a/src/channels/plugins/read-only-command-defaults.test.ts b/src/channels/plugins/read-only-command-defaults.test.ts
index e4297c2c881b..347a2ede4522 100644
--- a/src/channels/plugins/read-only-command-defaults.test.ts
+++ b/src/channels/plugins/read-only-command-defaults.test.ts
@@ -1,11 +1,15 @@
 // Read-only command default tests cover command defaulting for read-only channel plugins.
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { STATE_DIR } from "../../config/paths.js";
 
-const loadPluginMetadataSnapshot = vi.hoisted(() => vi.fn());
+const { loadPluginMetadataSnapshot, resolvePluginMetadataSnapshot } = vi.hoisted(() => ({
+  loadPluginMetadataSnapshot: vi.fn(),
+  resolvePluginMetadataSnapshot: vi.fn(),
+}));
 
 vi.mock("../../plugins/plugin-metadata-snapshot.js", () => ({
   loadPluginMetadataSnapshot,
-  resolvePluginMetadataSnapshot: loadPluginMetadataSnapshot,
+  resolvePluginMetadataSnapshot,
 }));
 
 import { resolveReadOnlyChannelCommandDefaults } from "./read-only-command-defaults.js";
@@ -13,10 +17,31 @@ import { resolveReadOnlyChannelCommandDefaults } from "./read-only-command-defau
 describe("resolveReadOnlyChannelCommandDefaults", () => {
   beforeEach(() => {
     loadPluginMetadataSnapshot.mockReset();
+    resolvePluginMetadataSnapshot.mockReset();
     loadPluginMetadataSnapshot.mockReturnValue({
       index: { plugins: [] },
       plugins: [],
     });
+    resolvePluginMetadataSnapshot.mockImplementation(loadPluginMetadataSnapshot);
+  });
+
+  it.each([
+    { name: "process", env: process.env, stateDir: STATE_DIR },
+    {
+      name: "custom",
+      env: { HOME: "/home/demo", OPENCLAW_STATE_DIR: "/state" },
+      stateDir: "/state",
+    },
+  ])("reuses published metadata for the $name state root without scanning", ({ env, stateDir }) => {
+    const currentSnapshot = { index: { plugins: [] }, plugins: [] };
+    resolvePluginMetadataSnapshot.mockImplementation((params) =>
+      params.stateDir === undefined ? currentSnapshot : loadPluginMetadataSnapshot(params),
+    );
+
+    expect(resolveReadOnlyChannelCommandDefaults("demo", { config: {}, env, stateDir })).toBe(
+      undefined,
+    );
+    expect(loadPluginMetadataSnapshot).not.toHaveBeenCalled();
   });
 
   it("resolves command defaults from the shared metadata snapshot", () => {
diff --git a/src/channels/plugins/read-only-command-defaults.ts b/src/channels/plugins/read-only-command-defaults.ts
index 857feb4170e2..c821e58d0562 100644
--- a/src/channels/plugins/read-only-command-defaults.ts
+++ b/src/channels/plugins/read-only-command-defaults.ts
@@ -4,6 +4,7 @@
  * Reads native command/skill defaults from installed plugin manifests without loading plugins.
  */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
+import { resolveStateDir, STATE_DIR } from "../../config/paths.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { isBlockedObjectKey } from "../../infra/prototype-keys.js";
 import { isInstalledPluginEnabled } from "../../plugins/installed-plugin-index.js";
@@ -87,7 +88,11 @@ export function resolveReadOnlyChannelCommandDefaults(
   const env = options.env ?? process.env;
   const resolvedSnapshot = resolvePluginMetadataSnapshot({
     config: options.config,
-    stateDir: options.stateDir,
+    stateDir:
+      options.stateDir !== undefined &&
+      options.stateDir === (env === process.env ? STATE_DIR : resolveStateDir(env))
+        ? undefined
+        : options.stateDir,
     workspaceDir: options.workspaceDir,
     env,
     allowWorkspaceScopedCurrent: true,
diff --git a/src/hooks/plugin-hooks.test.ts b/src/hooks/plugin-hooks.test.ts
index 5e24ca0d24b7..8b334c90aa93 100644
--- a/src/hooks/plugin-hooks.test.ts
+++ b/src/hooks/plugin-hooks.test.ts
@@ -3,8 +3,10 @@ import fs from "node:fs";
 import fsp from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
+import { setCurrentPluginMetadataSnapshot } from "../plugins/current-plugin-metadata-snapshot.js";
+import { loadPluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js";
 import {
   clearInternalHooks,
   createInternalHookEvent,
@@ -12,6 +14,7 @@ import {
   triggerInternalHook,
 } from "./internal-hooks.js";
 import { loadInternalHooks } from "./loader.js";
+import { resolvePluginHookDirs } from "./plugin-hooks.js";
 import { loadWorkspaceHookEntries } from "./workspace.js";
 
 describe("bundle plugin hooks", () => {
@@ -34,6 +37,8 @@ describe("bundle plugin hooks", () => {
   });
 
   afterEach(() => {
+    setCurrentPluginMetadataSnapshot(undefined);
+    vi.restoreAllMocks();
     clearInternalHooks();
     setInternalHooksEnabled(true);
     if (previousBundledHooksDir === undefined) {
@@ -125,6 +130,24 @@ describe("bundle plugin hooks", () => {
     expect(entry.metadata?.events).toEqual(["command:new"]);
   });
 
+  it("reuses published plugin metadata without rescanning manifests", async () => {
+    const bundleRoot = await writeBundleHookFixture();
+    const config = createConfig(true);
+    const snapshot = loadPluginMetadataSnapshot({ config, workspaceDir, env: process.env });
+    setCurrentPluginMetadataSnapshot(snapshot, { config, workspaceDir });
+    const hookDir = fs.realpathSync.native(path.join(bundleRoot, "hooks"));
+    const manifestRegistry = await import("../plugins/manifest-registry-installed.js");
+    const scanManifests = vi.spyOn(manifestRegistry, "loadPluginManifestRegistryForInstalledIndex");
+
+    for (let iteration = 0; iteration < 2; iteration += 1) {
+      expect(resolvePluginHookDirs({ workspaceDir, config })).toEqual([
+        { dir: hookDir, pluginId: "sample-bundle" },
+      ]);
+    }
+
+    expect(scanManifests).not.toHaveBeenCalled();
+  });
+
   it("loads and executes enabled bundle hooks through the internal hook loader", async () => {
     await writeBundleHookFixture();
 
diff --git a/src/hooks/plugin-hooks.ts b/src/hooks/plugin-hooks.ts
index d737de099ac0..a5999c1a4b27 100644
--- a/src/hooks/plugin-hooks.ts
+++ b/src/hooks/plugin-hooks.ts
@@ -8,7 +8,7 @@ import {
   resolvePolicyPluginActivationState,
 } from "../plugins/config-policy.js";
 import { resolveMemorySlotDecision } from "../plugins/config-state.js";
-import { loadPluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js";
+import { resolvePluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js";
 import { hasKind } from "../plugins/slots.js";
 import { isPathInsideWithRealpath } from "../security/scan-paths.js";
 
@@ -28,9 +28,9 @@ export function resolvePluginHookDirs(params: {
   if (!workspaceDir) {
     return [];
   }
-  const metadataSnapshot = loadPluginMetadataSnapshot({
+  const metadataSnapshot = resolvePluginMetadataSnapshot({
     workspaceDir,
-    config: params.config ?? {},
+    config: params.config,
     env: process.env,
   });
   const registry = metadataSnapshot.manifestRegistry;
diff --git a/src/plugins/tools.optional.test.ts b/src/plugins/tools.optional.test.ts
index d0c60709ef95..2e747b504393 100644
--- a/src/plugins/tools.optional.test.ts
+++ b/src/plugins/tools.optional.test.ts
@@ -2269,6 +2269,47 @@ describe("resolvePluginTools optional tools", () => {
     expect(factory).toHaveBeenCalledTimes(2);
   });
 
+  it("executes cached plugin tools from the published generation without rescanning manifests", async () => {
+    const context = createContext();
+    const runtimeConfig: OpenClawConfig = {
+      ...context.config,
+      channels: { telegram: { enabled: false } },
+    };
+    const getRuntimeConfig = vi.fn(() => runtimeConfig);
+    const toolContext = { ...context, getRuntimeConfig };
+    const factory = vi.fn(() => makeTool("cached_generation_tool"));
+    setRegistry(
+      [
+        createNamedToolEntry("cache-generation", "cached_generation_tool", {
+          factory,
+        }),
+      ],
+      context.config,
+    );
+
+    resolvePluginTools(createResolveToolsParams({ context: toolContext }));
+    const [cachedTool] = resolvePluginTools(createResolveToolsParams({ context: toolContext }));
+    expect(cachedTool?.name).toBe("cached_generation_tool");
+    expect(getRuntimeConfig).toHaveBeenCalledTimes(2);
+
+    const manifestRegistry = await import("./manifest-registry-installed.js");
+    const manifestScan = vi
+      .spyOn(manifestRegistry, "loadPluginManifestRegistryForInstalledIndex")
+      .mockImplementation(() => {
+        throw new Error("cached plugin execution rescanned manifests");
+      });
+    try {
+      await expect(cachedTool?.execute("call", {}, undefined)).resolves.toEqual({
+        content: [{ type: "text", text: "ok" }],
+      });
+      expect(manifestScan).not.toHaveBeenCalled();
+      expect(getRuntimeConfig).toHaveBeenCalledTimes(2);
+      expect(factory).toHaveBeenCalledTimes(2);
+    } finally {
+      manifestScan.mockRestore();
+    }
+  });
+
   it("keeps cached ordinary plugin tools free of network provenance", async () => {
     const factory = vi.fn(() => makeTool("cached_ordinary_tool"));
     setRegistry([
diff --git a/src/plugins/tools.ts b/src/plugins/tools.ts
index 7d8d2c739101..6e6243a9ad54 100644
--- a/src/plugins/tools.ts
+++ b/src/plugins/tools.ts
@@ -31,6 +31,7 @@ import {
 } from "./manifest-contract-eligibility.js";
 import type { PluginManifestRecord } from "./manifest-registry.js";
 import { hasManifestToolAvailability } from "./manifest-tool-availability.js";
+import { resolvePluginMetadataSnapshot } from "./plugin-metadata-snapshot.js";
 import type { PluginMetadataManifestView } from "./plugin-metadata-snapshot.types.js";
 import type { PluginRegistry, PluginToolRegistration } from "./registry-types.js";
 import {
@@ -292,26 +293,6 @@ function blocksHostRestrictedConversationReadRegistration(params: {
   );
 }
 
-function resolveCurrentManifestPlugin(params: {
-  pluginId: string;
-  ctx: OpenClawPluginToolContext;
-  loadContext: ReturnType<typeof resolvePluginRuntimeLoadContext>;
-}): PluginManifestRecord | undefined {
-  let config = params.ctx.runtimeConfig ?? params.ctx.config ?? params.loadContext.config;
-  if (params.ctx.getRuntimeConfig) {
-    try {
-      config = params.ctx.getRuntimeConfig() ?? config;
-    } catch {
-      return undefined;
-    }
-  }
-  return loadManifestContractSnapshot({
-    config,
-    workspaceDir: params.loadContext.workspaceDir,
-    env: params.loadContext.env,
-  }).plugins.find((plugin) => plugin.id === params.pluginId);
-}
-
 /**
  * Builds a collision-proof key for plugin-owned tool metadata lookups.
  */
@@ -876,11 +857,11 @@ function createCachedDescriptorPluginTool(params: {
       const resolveCandidateTool = (
         candidate: PluginToolRegistration,
       ): AnyAgentTool | undefined => {
-        const manifestPlugin = resolveCurrentManifestPlugin({
-          pluginId,
-          ctx: params.ctx,
-          loadContext: params.loadContext,
-        });
+        const manifestPlugin = resolvePluginMetadataSnapshot({
+          config: params.loadContext.config,
+          workspaceDir: params.loadContext.workspaceDir,
+          env: params.loadContext.env,
+        }).byPluginId.get(pluginId);
         if (
           blocksHostRestrictedConversationReadRegistration({
             entry: candidate,
diff --git a/src/secrets/channel-env-vars.dynamic.test.ts b/src/secrets/channel-env-vars.dynamic.test.ts
index 9bfbd0a9c782..57f03b6e94f5 100644
--- a/src/secrets/channel-env-vars.dynamic.test.ts
+++ b/src/secrets/channel-env-vars.dynamic.test.ts
@@ -18,14 +18,16 @@ const pluginRegistryMocks = vi.hoisted(() => {
     plugins: [],
     diagnostics: [],
   }));
+  const loadPluginMetadataSnapshot = vi.fn((_params?: unknown) => ({
+    plugins: loadManifestRegistry().plugins,
+    manifestRegistry: loadManifestRegistry(),
+  }));
   return {
     loadPluginManifestRegistryForInstalledIndex: loadManifestRegistry,
     loadPluginManifestRegistryForPluginRegistry: loadManifestRegistry,
     loadPluginRegistrySnapshot: vi.fn(() => ({ plugins: [] })),
-    loadPluginMetadataSnapshot: vi.fn(() => ({
-      plugins: loadManifestRegistry().plugins,
-      manifestRegistry: loadManifestRegistry(),
-    })),
+    loadPluginMetadataSnapshot,
+    resolvePluginMetadataSnapshot: vi.fn((params: unknown) => loadPluginMetadataSnapshot(params)),
   };
 });
 
@@ -42,6 +44,7 @@ vi.mock("../plugins/plugin-registry.js", () => ({
 
 vi.mock("../plugins/plugin-metadata-snapshot.js", () => ({
   loadPluginMetadataSnapshot: pluginRegistryMocks.loadPluginMetadataSnapshot,
+  resolvePluginMetadataSnapshot: pluginRegistryMocks.resolvePluginMetadataSnapshot,
 }));
 
 describe("channel env vars dynamic package metadata", () => {
@@ -55,6 +58,10 @@ describe("channel env vars dynamic package metadata", () => {
     pluginRegistryMocks.loadPluginRegistrySnapshot.mockReset();
     pluginRegistryMocks.loadPluginRegistrySnapshot.mockReturnValue({ plugins: [] });
     pluginRegistryMocks.loadPluginMetadataSnapshot.mockClear();
+    pluginRegistryMocks.resolvePluginMetadataSnapshot.mockReset();
+    pluginRegistryMocks.resolvePluginMetadataSnapshot.mockImplementation((params) =>
+      pluginRegistryMocks.loadPluginMetadataSnapshot(params),
+    );
   });
 
   it("includes later-installed plugin env vars without a bundled generated map", async () => {
@@ -81,4 +88,31 @@ describe("channel env vars dynamic package metadata", () => {
     expect(knownNames).toContain("MATTERMOST_BOT_TOKEN");
     expect(knownNames).toContain("MATTERMOST_URL");
   });
+
+  it("reuses published channel metadata without rescanning manifests", async () => {
+    pluginRegistryMocks.resolvePluginMetadataSnapshot.mockReturnValue({
+      plugins: [
+        {
+          id: "external-mattermost",
+          origin: "global",
+          packageChannel: {
+            id: "mattermost",
+            configuredState: { env: { anyOf: ["MATTERMOST_BOT_TOKEN"] } },
+          },
+        },
+      ],
+      manifestRegistry: { plugins: [], diagnostics: [] },
+    });
+    const mod = await import("./channel-env-vars.js");
+
+    expect(mod.getChannelEnvVars("mattermost")).toEqual(["MATTERMOST_BOT_TOKEN"]);
+    expect(mod.listKnownChannelEnvVarNames()).toEqual(["MATTERMOST_BOT_TOKEN"]);
+    expect(pluginRegistryMocks.loadPluginMetadataSnapshot).not.toHaveBeenCalled();
+    expect(pluginRegistryMocks.resolvePluginMetadataSnapshot).toHaveBeenCalledTimes(2);
+    expect(pluginRegistryMocks.resolvePluginMetadataSnapshot).toHaveBeenCalledWith({
+      config: undefined,
+      workspaceDir: undefined,
+      env: process.env,
+    });
+  });
 });
diff --git a/src/secrets/channel-env-vars.ts b/src/secrets/channel-env-vars.ts
index 9b7f73593f14..8dfe6d66c176 100644
--- a/src/secrets/channel-env-vars.ts
+++ b/src/secrets/channel-env-vars.ts
@@ -1,7 +1,7 @@
 /** Discovers plugin-declared environment variable names for channel credential setup. */
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
-import { loadPluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js";
+import { resolvePluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js";
 import { appendUniqueEnvVarCandidates } from "../shared/env-var-candidates.js";
 
 type ChannelEnvVarLookupParams = {
@@ -20,8 +20,8 @@ type ChannelEnvVarLookupParams = {
 function resolveChannelEnvVars(
   params?: ChannelEnvVarLookupParams,
 ): Record<string, readonly string[]> {
-  const snapshot = loadPluginMetadataSnapshot({
-    config: params?.config ?? {},
+  const snapshot = resolvePluginMetadataSnapshot({
+    config: params?.config,
     workspaceDir: params?.workspaceDir,
     env: params?.env ?? process.env,
   });
diff --git a/src/skills/loading/plugin-skills.test.ts b/src/skills/loading/plugin-skills.test.ts
index 656b240f5558..4568f606afb3 100644
--- a/src/skills/loading/plugin-skills.test.ts
+++ b/src/skills/loading/plugin-skills.test.ts
@@ -302,6 +302,24 @@ describe("resolvePluginSkillDirs", () => {
     expect(hoisted.loadPluginMetadataSnapshot).not.toHaveBeenCalled();
   });
 
+  it("preserves absent config when resolving current lifecycle metadata", async () => {
+    const workspaceDir = await tempDirs.make("openclaw-");
+    const manifestRegistry: PluginManifestRegistry = { diagnostics: [], plugins: [] };
+    const metadataSnapshot = {
+      manifestRegistry,
+      plugins: manifestRegistry.plugins,
+      normalizePluginId: (pluginId: string) => pluginId,
+    };
+    hoisted.resolvePluginMetadataSnapshot.mockImplementationOnce((params: unknown) =>
+      (params as { config?: OpenClawConfig }).config === undefined
+        ? metadataSnapshot
+        : hoisted.loadPluginMetadataSnapshot(params),
+    );
+
+    expect(resolvePluginSkillDirs({ workspaceDir })).toEqual([]);
+    expect(hoisted.loadPluginMetadataSnapshot).not.toHaveBeenCalled();
+  });
+
   it.each([
     {
       name: "unavailable to available",
diff --git a/src/skills/loading/plugin-skills.ts b/src/skills/loading/plugin-skills.ts
index 0220d2ce36a8..331fd9798915 100644
--- a/src/skills/loading/plugin-skills.ts
+++ b/src/skills/loading/plugin-skills.ts
@@ -50,10 +50,9 @@ export function resolvePluginSkillDirs(params: {
     });
     return [];
   }
-  const config = params.config ?? {};
   const metadataSnapshot = resolvePluginMetadataSnapshot({
     workspaceDir,
-    config,
+    config: params.config,
     env: process.env,
   });
   return resolvePluginSkillDirsFromMetadata({ ...params, metadataSnapshot });

From 0a20c5715450637284f2cbd3800fcc559474dfd1 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 11:34:59 -0700
Subject: [PATCH 060/124] fix(sessions): preserve ownership across lifecycle
 and maintenance (#127344)

* fix(sessions): preserve ownership across lifecycle and maintenance

* test(gateway): recognize owner-complete session projections
---
 .../session-accessor.sqlite-entry-store.ts    |  5 +--
 ...session-accessor.sqlite-lifecycle-state.ts |  2 +-
 .../session-accessor.sqlite-maintenance.ts    | 26 ++++------------
 .../session-accessor.sqlite-status.ts         |  5 +--
 src/config/sessions/session-accessor.test.ts  | 19 ++++++++++--
 .../sessions-mutations.perf.test.ts           | 30 +++++++++---------
 src/plugin-sdk/session-store-runtime.test.ts  | 31 ++++++++++---------
 7 files changed, 57 insertions(+), 61 deletions(-)

diff --git a/src/config/sessions/session-accessor.sqlite-entry-store.ts b/src/config/sessions/session-accessor.sqlite-entry-store.ts
index 3d654ed311be..1955dd3ecc0a 100644
--- a/src/config/sessions/session-accessor.sqlite-entry-store.ts
+++ b/src/config/sessions/session-accessor.sqlite-entry-store.ts
@@ -262,10 +262,7 @@ export function readSessionEntryStore(
   const db = getSessionKysely(database.db);
   const rows = executeSqliteQuerySync(
     database.db,
-    db
-      .selectFrom("session_nodes")
-      .select(["current_session_id", "entry_json", "session_key", "updated_at"])
-      .orderBy("session_key"),
+    db.selectFrom("session_nodes").selectAll().orderBy("session_key"),
   ).rows;
   const store: Record<string, SessionEntry> = {};
   for (const row of rows) {
diff --git a/src/config/sessions/session-accessor.sqlite-lifecycle-state.ts b/src/config/sessions/session-accessor.sqlite-lifecycle-state.ts
index 2e334a6df8d2..c3e7bc0a3aa1 100644
--- a/src/config/sessions/session-accessor.sqlite-lifecycle-state.ts
+++ b/src/config/sessions/session-accessor.sqlite-lifecycle-state.ts
@@ -627,7 +627,7 @@ export function planSessionLifecycleArtifactCleanup(
     ) {
       continue;
     }
-    const entry = parseSessionEntryRow(row);
+    const entry = projectedStore[row.session_key];
     const sessionIds = uniqueStrings([
       row.current_session_id,
       ...(entry ? collectSessionStateIdsForEntry(entry) : []),
diff --git a/src/config/sessions/session-accessor.sqlite-maintenance.ts b/src/config/sessions/session-accessor.sqlite-maintenance.ts
index ba147ded8ad8..69f643f8b01e 100644
--- a/src/config/sessions/session-accessor.sqlite-maintenance.ts
+++ b/src/config/sessions/session-accessor.sqlite-maintenance.ts
@@ -11,7 +11,11 @@ import {
   type SessionStateDeletePlan,
 } from "./session-accessor.sqlite-archive.js";
 import type { SessionLifecycleArchivedTranscript } from "./session-accessor.sqlite-contract.js";
-import { readSessionEntryCount, writeSessionEntry } from "./session-accessor.sqlite-entry-store.js";
+import {
+  readSessionEntryCount,
+  readSessionEntryStore,
+  writeSessionEntry,
+} from "./session-accessor.sqlite-entry-store.js";
 import { emitCommittedSessionEntryRemovals } from "./session-accessor.sqlite-identity.js";
 import {
   assertPlannedLifecycleArtifactEntriesUnchanged,
@@ -98,24 +102,6 @@ function hasStaleSqliteSessionEntryCandidate(
   });
 }
 
-function loadSqliteSessionMaintenanceStore(
-  database: OpenClawAgentDatabase,
-): Record<string, SessionEntry> {
-  const db = getSessionKysely(database.db);
-  const rows = executeSqliteQuerySync(
-    database.db,
-    db.selectFrom("session_nodes").select(["session_key", "entry_json"]).orderBy("session_key"),
-  ).rows;
-  const store: Record<string, SessionEntry> = {};
-  for (const row of rows) {
-    const entry = parseSessionEntryRow(row);
-    if (entry) {
-      store[row.session_key] = entry;
-    }
-  }
-  return store;
-}
-
 export function applySessionEntryMaintenance(
   database: OpenClawAgentDatabase,
   params: {
@@ -203,7 +189,7 @@ export function applySessionEntryMaintenance(
     };
   }
 
-  const store = loadSqliteSessionMaintenanceStore(database);
+  const store = readSessionEntryStore(database);
   const preserveKeys =
     collectSessionMaintenancePreserveKeysForStore({
       storePath: params.storePath,
diff --git a/src/config/sessions/session-accessor.sqlite-status.ts b/src/config/sessions/session-accessor.sqlite-status.ts
index 2474ca434e78..b293fc58d5b9 100644
--- a/src/config/sessions/session-accessor.sqlite-status.ts
+++ b/src/config/sessions/session-accessor.sqlite-status.ts
@@ -52,10 +52,7 @@ export function readSessionEntriesByStatus(
     return [];
   }
   const db = getNodeSqliteKysely<SessionStatusDatabase>(database.db);
-  let query = db
-    .selectFrom("session_nodes")
-    .select(["session_key", "entry_json", "current_session_id", "updated_at"])
-    .where("status", "in", selectedStatuses);
+  let query = db.selectFrom("session_nodes").selectAll().where("status", "in", selectedStatuses);
   if (selectedSessionKeys) {
     query = query.where("session_key", "in", selectedSessionKeys);
   }
diff --git a/src/config/sessions/session-accessor.test.ts b/src/config/sessions/session-accessor.test.ts
index 5c78525ae616..bd35f1cfbf9e 100644
--- a/src/config/sessions/session-accessor.test.ts
+++ b/src/config/sessions/session-accessor.test.ts
@@ -33,6 +33,7 @@ import {
   appendTranscriptEvent,
   appendTranscriptMessage,
   applySessionEntryLifecycleMutation,
+  assignSessionOwner,
   commitReplySessionInitialization,
   countSessionEntryRowsReadOnly,
   createSessionEntryWithTranscript,
@@ -2119,6 +2120,11 @@ describe("session accessor seam", () => {
       ],
       skipMaintenance: true,
     });
+    const doneOwner = { id: "done-owner", type: "human" as const };
+    assignSessionOwner(
+      { sessionKey: "agent:main:done", storePath },
+      { assignedBy: doneOwner, owner: doneOwner },
+    );
 
     const result = await applySessionEntryReplacements({
       storePath,
@@ -2169,9 +2175,12 @@ describe("session accessor seam", () => {
       "agent:main:other",
       "agent:main:shared-running",
     ]);
-    expect(
-      listSessionEntriesByStatus({ storePath }, ["done"]).map((entry) => entry.sessionKey),
-    ).toEqual(["agent:main:done", "agent:main:shared-done"]);
+    const doneSessions = listSessionEntriesByStatus({ storePath }, ["done"]);
+    expect(doneSessions.map((entry) => entry.sessionKey)).toEqual([
+      "agent:main:done",
+      "agent:main:shared-done",
+    ]);
+    expect(doneSessions[0]?.entry.owner?.actor).toEqual(doneOwner);
 
     const other = loadSessionEntry({ sessionKey: "agent:main:other", storePath });
     expect(other).toBeDefined();
@@ -2592,6 +2601,8 @@ describe("session accessor seam", () => {
       sessionId: "lifecycle-prepare",
       updatedAt: 10,
     });
+    const owner = { id: "lifecycle-owner", type: "human" as const };
+    assignSessionOwner(scope, { assignedBy: owner, owner });
     const builderStarted = createDeferred();
     const builderGate = createDeferred();
     const pendingMutation = applySessionEntryLifecycleMutation({
@@ -2696,6 +2707,8 @@ describe("session accessor seam", () => {
       sessionId: scope.sessionId,
       updatedAt: 10,
     });
+    const owner = { id: "lifecycle-owner", type: "human" as const };
+    assignSessionOwner(scope, { assignedBy: owner, owner });
     await replaceTranscriptEvents(scope, [
       {
         id: "event-1",
diff --git a/src/gateway/server-methods/sessions-mutations.perf.test.ts b/src/gateway/server-methods/sessions-mutations.perf.test.ts
index e666bf65d4d4..1b3e1c867883 100644
--- a/src/gateway/server-methods/sessions-mutations.perf.test.ts
+++ b/src/gateway/server-methods/sessions-mutations.perf.test.ts
@@ -54,6 +54,20 @@ function humanClient(): GatewayClient {
   };
 }
 
+function isWholeSessionStoreProjection(normalizedSql: string): boolean {
+  const source = ' from "session_nodes" order by "session_key"';
+  if (!normalizedSql.startsWith("select ") || !normalizedSql.endsWith(source)) {
+    return false;
+  }
+  const selection = normalizedSql.slice("select ".length, -source.length);
+  return (
+    selection === "*" ||
+    ['"current_session_id"', '"entry_json"', '"session_key"', '"updated_at"'].every((column) =>
+      selection.includes(column),
+    )
+  );
+}
+
 test("single non-label sessions.patch avoids a whole-store projection", async () => {
   await withOpenClawTestState({ scenario: "minimal" }, async (state) => {
     const targetKey = "agent:main:single-patch-target";
@@ -74,13 +88,7 @@ test("single non-label sessions.patch avoids a whole-store projection", async ()
       ["whole-store-projection"] as const,
       (sql) => {
         const normalized = sql.toLowerCase().replaceAll(/\s+/g, " ").trim();
-        return normalized.includes(
-          'select "current_session_id", "entry_json", "session_key", "updated_at"',
-        ) &&
-          normalized.includes('from "session_nodes"') &&
-          normalized.includes('order by "session_key"')
-          ? "whole-store-projection"
-          : null;
+        return isWholeSessionStoreProjection(normalized) ? "whole-store-projection" : null;
       },
     );
     const respond = vi.fn();
@@ -159,13 +167,7 @@ test("sessions.patchMany archives 30 human sessions without transcript hydration
       ["whole-store-projection", "transcript-full-hydration"] as const,
       (sql) => {
         const normalized = sql.toLowerCase().replaceAll(/\s+/g, " ").trim();
-        if (
-          normalized.includes(
-            'select "current_session_id", "entry_json", "session_key", "updated_at"',
-          ) &&
-          normalized.includes('from "session_nodes"') &&
-          normalized.includes('order by "session_key"')
-        ) {
+        if (isWholeSessionStoreProjection(normalized)) {
           return "whole-store-projection";
         }
         const fromIndex = normalized.indexOf(" from ");
diff --git a/src/plugin-sdk/session-store-runtime.test.ts b/src/plugin-sdk/session-store-runtime.test.ts
index 159e64179938..7855cd8f18fd 100644
--- a/src/plugin-sdk/session-store-runtime.test.ts
+++ b/src/plugin-sdk/session-store-runtime.test.ts
@@ -5,6 +5,7 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
   appendTranscriptEvent,
   appendTranscriptMessage,
+  assignSessionOwner,
   loadSessionEntry as loadInternalSessionEntry,
   patchSessionEntryCore as patchInternalSessionEntry,
   replaceSessionEntry as replaceInternalSessionEntry,
@@ -63,6 +64,11 @@ describe("session-store-runtime compatibility surface", () => {
     });
   }
 
+  function assignOwner(sessionKey: string): void {
+    const actor = { id: "profile-owner", type: "human" as const };
+    assignSessionOwner({ sessionKey, storePath }, { assignedBy: actor, owner: actor });
+  }
+
   function expectRecoveryCleared(params: {
     sessionId: string;
     sessionKey: string;
@@ -321,15 +327,13 @@ describe("session-store-runtime compatibility surface", () => {
   });
 
   it("applies whole-store compatibility mutations through SQLite rows", async () => {
-    await seedSessionEntry("agent:main:remove", {
-      sessionId: "session-remove",
-      updatedAt: 10,
-    });
+    await seedSessionEntry("agent:main:remove", { sessionId: "session-remove", updatedAt: 10 });
     await seedSessionEntry("agent:main:update", {
       model: "gpt-5.5",
       sessionId: "session-update",
       updatedAt: 10,
     });
+    ["agent:main:remove", "agent:main:update"].forEach(assignOwner);
 
     await expect(
       updateSessionStore(
@@ -829,6 +833,7 @@ describe("session-store-runtime compatibility surface", () => {
         sessionId: "session-active",
         updatedAt: now,
       });
+      assignOwner(staleSessionKey);
 
       await patchSessionEntry({
         sessionKey: activeSessionKey,
@@ -996,20 +1001,16 @@ describe("session-store-runtime compatibility surface", () => {
   });
 
   it("cleans lifecycle artifacts through the accessor-backed SDK wrapper", async () => {
-    const sessionKey = "agent:main:lifecycle-owned-old";
+    const sessionId = "lifecycle-owned-old";
+    const sessionKey = `agent:main:${sessionId}`;
     const oldTimestamp = Date.now() - 600_000;
-    await seedSessionEntry(sessionKey, {
-      sessionId: "lifecycle-owned-old",
-      updatedAt: oldTimestamp,
-    });
-    await seedSessionEntry("agent:main:regular", {
-      sessionId: "regular",
-      updatedAt: Date.now(),
-    });
+    await seedSessionEntry(sessionKey, { sessionId, updatedAt: oldTimestamp });
+    await seedSessionEntry("agent:main:regular", { sessionId: "regular", updatedAt: Date.now() });
+    assignOwner(sessionKey);
     await appendTranscriptEvent(
-      { agentId: "main", sessionKey, sessionId: "lifecycle-owned-old", storePath },
+      { agentId: "main", sessionKey, sessionId, storePath },
       {
-        runId: "lifecycle-owned-old",
+        runId: sessionId,
         timestamp: new Date(oldTimestamp).toISOString(),
         type: "metadata",
       },

From 4324ba2f484b10c299eff22e120b07fc250bef43 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 11:39:11 -0700
Subject: [PATCH 061/124] test: canonicalize macOS temporary workspace paths
 (#127366)

---
 src/agents/sandbox/fs-bridge.test-helpers.ts                  | 2 +-
 .../tools/skill-workshop-tool.collection-restore.test.ts      | 4 +++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/agents/sandbox/fs-bridge.test-helpers.ts b/src/agents/sandbox/fs-bridge.test-helpers.ts
index 74049730d478..0f097431f4d2 100644
--- a/src/agents/sandbox/fs-bridge.test-helpers.ts
+++ b/src/agents/sandbox/fs-bridge.test-helpers.ts
@@ -170,7 +170,7 @@ export async function withTempDir<T>(
   prefix: string,
   run: (stateDir: string) => Promise<T>,
 ): Promise<T> {
-  const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+  const stateDir = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), prefix)));
   try {
     return await run(stateDir);
   } finally {
diff --git a/src/agents/tools/skill-workshop-tool.collection-restore.test.ts b/src/agents/tools/skill-workshop-tool.collection-restore.test.ts
index 99505a4889ad..46c50b1ded2b 100644
--- a/src/agents/tools/skill-workshop-tool.collection-restore.test.ts
+++ b/src/agents/tools/skill-workshop-tool.collection-restore.test.ts
@@ -21,7 +21,9 @@ describe("skill_workshop collection restore", () => {
       prefix: "openclaw-skill-collection-restore-state-",
     });
     cleanups.push(async () => await testState.cleanup());
-    const workspaceDir = await tempDirs.make("openclaw-skill-collection-restore-");
+    const workspaceDir = await fs.realpath(
+      await tempDirs.make("openclaw-skill-collection-restore-"),
+    );
     const proposal = await proposeCreateSkill({
       workspaceDir,
       env: testState.env,

From 01e888795978ede45f9cbeaf6d8bfc4bbbb9987d Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 11:40:52 -0700
Subject: [PATCH 062/124] refactor(providers): return prepared dynamic models
 directly (#126574)

---
 docs/plugins/architecture-internals.md        |   2 +-
 docs/plugins/sdk-provider-plugins.md          |   8 +-
 extensions/llama-cpp/index.test.ts            |  24 ++
 .../src/external-server/provider.test.ts      | 221 +++++++++---------
 .../llama-cpp/src/external-server/provider.ts |  77 ++----
 extensions/llama-cpp/src/managed-provider.ts  |  12 +-
 extensions/lmstudio/api.ts                    |   2 +-
 extensions/lmstudio/index.test.ts             | 114 ++++++++-
 extensions/lmstudio/index.ts                  |  12 +-
 extensions/lmstudio/src/api.ts                |   2 +-
 extensions/lmstudio/src/setup.ts              |  27 ++-
 extensions/ollama/index.test.ts               | 103 ++++----
 extensions/ollama/index.ts                    | 130 ++---------
 .../model.provider-hooks.ts                   |   2 +-
 .../model.registry-resolution.ts              |  52 ++---
 .../embedded-agent-runner/model.test.ts       | 121 ++++++++++
 src/agents/embedded-agent-runner/model.ts     |   3 +-
 .../live-model-dynamic-candidates.test.ts     |  21 ++
 .../live-model-dynamic-candidates.ts          |  22 +-
 src/plugins/provider-plugin.types.ts          |  14 +-
 src/plugins/provider-runtime.test.ts          |  14 +-
 src/plugins/provider-runtime.ts               |   4 +-
 src/plugins/provider-runtime.types.ts         |   7 +-
 23 files changed, 562 insertions(+), 432 deletions(-)

diff --git a/docs/plugins/architecture-internals.md b/docs/plugins/architecture-internals.md
index 343c73dd91e5..7e86b927e3a0 100644
--- a/docs/plugins/architecture-internals.md
+++ b/docs/plugins/architecture-internals.md
@@ -272,7 +272,7 @@ listed here.
 | `resolveExternalAuthProfiles`     | Overlay provider-owned external auth profiles; default `persistence` is `runtime-only` for CLI/app-owned creds | Provider reuses external auth credentials without persisting copied refresh tokens; declare `contracts.externalAuthProviders` in the manifest |
 | `shouldDeferSyntheticProfileAuth` | Lower stored synthetic profile placeholders behind env/config-backed auth                                      | Provider stores synthetic placeholder profiles that should not win precedence                                                                 |
 | `resolveDynamicModel`             | Sync fallback for provider-owned model ids not in the local registry yet                                       | Provider accepts arbitrary upstream model ids                                                                                                 |
-| `prepareDynamicModel`             | Async warm-up, then `resolveDynamicModel` runs again                                                           | Provider needs network metadata before resolving unknown ids                                                                                  |
+| `prepareDynamicModel`             | Return an asynchronously prepared model, or warm reusable metadata before retrying `resolveDynamicModel`       | Provider needs network metadata before resolving unknown ids                                                                                  |
 | `normalizeResolvedModel`          | Final rewrite before the embedded runner uses the resolved model                                               | Provider needs transport rewrites but still uses a core transport                                                                             |
 | `normalizeToolSchemas`            | Normalize tool schemas before the embedded runner sees them                                                    | Provider needs transport-family schema cleanup                                                                                                |
 | `inspectToolSchemas`              | Surface provider-owned schema diagnostics after normalization                                                  | Provider wants keyword warnings without teaching core provider-specific rules                                                                 |
diff --git a/docs/plugins/sdk-provider-plugins.md b/docs/plugins/sdk-provider-plugins.md
index 9b24294591cd..eda32122a4c0 100644
--- a/docs/plugins/sdk-provider-plugins.md
+++ b/docs/plugins/sdk-provider-plugins.md
@@ -485,8 +485,10 @@ catalog, API-key auth, and dynamic model resolution.
     });
     ```
 
-    If resolving requires a network call, use `prepareDynamicModel` for async
-    warm-up - `resolveDynamicModel` runs again after it completes.
+    If resolving requires a network call, return the requested model directly
+    from `prepareDynamicModel`. OpenClaw applies the same configured overrides
+    and normalization as synchronous dynamic resolution. Existing hooks that
+    return nothing still retry `resolveDynamicModel` after preparation.
 
   </Step>
 
@@ -683,7 +685,7 @@ catalog, API-key auth, and dynamic model resolution.
       | `resolveExternalAuthProfiles` | Overlay provider-owned external auth profiles for CLI/app-managed credentials |
       | `shouldDeferSyntheticProfileAuth` | Lower synthetic stored-profile placeholders behind env/config auth |
       | `resolveDynamicModel` | Accept arbitrary upstream model IDs |
-      | `prepareDynamicModel` | Async metadata fetch before resolving |
+      | `prepareDynamicModel` | Return an asynchronously discovered model, or warm reusable metadata before sync resolution |
       | `normalizeResolvedModel` | Transport rewrites before the runner |
       | `normalizeToolSchemas` | Provider-owned tool-schema cleanup before registration |
       | `inspectToolSchemas` | Provider-owned tool-schema diagnostics |
diff --git a/extensions/llama-cpp/index.test.ts b/extensions/llama-cpp/index.test.ts
index 032401eb003b..3d9dac91f60c 100644
--- a/extensions/llama-cpp/index.test.ts
+++ b/extensions/llama-cpp/index.test.ts
@@ -18,6 +18,7 @@ import type { ProviderPlugin } from "openclaw/plugin-sdk/provider-model-shared";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
+  discoverServer: vi.fn(),
   ensureModel: vi.fn(),
   prepareServer: vi.fn(),
   inspectRuntime: vi.fn(),
@@ -36,6 +37,11 @@ vi.mock("./src/managed-server.js", async (importOriginal) => ({
   inspectLlamaServerRuntime: mocks.inspectRuntime,
 }));
 
+vi.mock("./src/external-server/discovery.js", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./src/external-server/discovery.js")>()),
+  discoverLlamaServer: mocks.discoverServer,
+}));
+
 import llamaCppPlugin from "./index.js";
 import {
   DEFAULT_LLAMA_CPP_EMBEDDING_CACHE_FILE,
@@ -52,6 +58,7 @@ let previousPluginRegistry: ReturnType<typeof getActivePluginRegistry>;
 
 beforeEach(() => {
   previousPluginRegistry = getActivePluginRegistry();
+  mocks.discoverServer.mockReset();
   mocks.ensureModel.mockResolvedValue("/models/model.gguf");
   mocks.prepareServer.mockResolvedValue({});
   mocks.inspectRuntime.mockResolvedValue({
@@ -171,6 +178,23 @@ describe("llama.cpp provider plugin", () => {
     expect(provider).not.toHaveProperty("createStreamFn");
   });
 
+  it("never discovers external models for a managed local service", async () => {
+    const provider = registerTextProvider();
+    const prepareDynamicModel = expectDefined(provider.prepareDynamicModel, "dynamic model hook");
+    const { config } = configuredOptions();
+
+    await expect(
+      prepareDynamicModel({
+        config,
+        provider: LLAMA_CPP_PROVIDER_ID,
+        modelId: "gemma-4-e4b-it-q4_k_m",
+        modelRegistry: {} as never,
+        providerConfig: config.models.providers[LLAMA_CPP_PROVIDER_ID],
+      }),
+    ).resolves.toBeUndefined();
+    expect(mocks.discoverServer).not.toHaveBeenCalled();
+  });
+
   it("registers local embeddings through the generic provider contract", () => {
     const { config, registry } = createPluginRegistryFixture();
     registerVirtualTestPlugin({
diff --git a/extensions/llama-cpp/src/external-server/provider.test.ts b/extensions/llama-cpp/src/external-server/provider.test.ts
index e0cd543f0c64..43e0a79db26f 100644
--- a/extensions/llama-cpp/src/external-server/provider.test.ts
+++ b/extensions/llama-cpp/src/external-server/provider.test.ts
@@ -3,11 +3,7 @@ import type {
   ProviderPrepareDynamicModelContext,
 } from "openclaw/plugin-sdk/plugin-entry";
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import {
-  discoverLlamaServerProvider,
-  prepareLlamaServerDynamicModels,
-  resolveLlamaServerDynamicModel,
-} from "./provider.js";
+import { discoverLlamaServerProvider, prepareLlamaServerDynamicModel } from "./provider.js";
 
 const discoverMock = vi.hoisted(() => vi.fn());
 const runtimeApiKeyMock = vi.hoisted(() => vi.fn());
@@ -64,6 +60,22 @@ function catalogContext(): ProviderCatalogContext {
   };
 }
 
+function dynamicContext(
+  overrides: Partial<ProviderPrepareDynamicModelContext> = {},
+): ProviderPrepareDynamicModelContext {
+  return {
+    config: {},
+    provider: "llama-cpp",
+    modelId: "org/model:Q4",
+    modelRegistry: {} as never,
+    providerConfig: {
+      baseUrl: "http://localhost:8080/v1",
+      api: "openai-completions",
+    },
+    ...overrides,
+  };
+}
+
 describe("llama-server provider discovery", () => {
   beforeEach(() => {
     discoverMock.mockReset();
@@ -131,7 +143,29 @@ describe("llama-server provider discovery", () => {
     });
   });
 
-  it("scopes dynamic catalogs by agent runtime and auth profile", async () => {
+  it("returns only the requested discovered model directly to its preparation owner", async () => {
+    discoverMock.mockResolvedValue({
+      ...success(),
+      models: [
+        model(),
+        {
+          ...model(),
+          config: { ...model().config, id: "org/requested:Q8", name: "Requested model" },
+        },
+      ],
+    });
+    await expect(
+      prepareLlamaServerDynamicModel(dynamicContext({ modelId: "org/requested:Q8" })),
+    ).resolves.toMatchObject({
+      provider: "llama-cpp",
+      id: "org/requested:Q8",
+      name: "Requested model",
+      baseUrl: "http://localhost:8080/v1",
+      api: "openai-completions",
+    });
+  });
+
+  it("keeps requested models and API keys isolated by agent runtime and auth profile", async () => {
     const first = success();
     const second = {
       ...success(),
@@ -143,29 +177,20 @@ describe("llama-server provider discovery", () => {
       ],
     };
     discoverMock.mockResolvedValueOnce(first).mockResolvedValueOnce(second);
-    const base = {
-      config: {},
-      provider: "llama-cpp",
-      modelId: "org/model:Q4",
-      modelRegistry: {},
-      providerConfig: {
-        baseUrl: "http://localhost:8080/v1",
-        api: "openai-completions",
-      },
-    };
-    const firstCtx = {
-      ...base,
+    runtimeApiKeyMock
+      .mockResolvedValueOnce("first-profile-key")
+      .mockResolvedValueOnce("second-profile-key");
+    const firstCtx = dynamicContext({
       agentRuntimeId: "runtime-one",
       authProfileId: "profile-one",
-    } as unknown as ProviderPrepareDynamicModelContext;
-    const secondCtx = {
-      ...base,
+    });
+    const secondCtx = dynamicContext({
       agentRuntimeId: "runtime-two",
       authProfileId: "profile-two",
-    } as unknown as ProviderPrepareDynamicModelContext;
+    });
 
-    await prepareLlamaServerDynamicModels(firstCtx);
-    await prepareLlamaServerDynamicModels(secondCtx);
+    const firstModel = await prepareLlamaServerDynamicModel(firstCtx);
+    const secondModel = await prepareLlamaServerDynamicModel(secondCtx);
 
     expect(runtimeApiKeyMock).toHaveBeenNthCalledWith(
       1,
@@ -175,111 +200,87 @@ describe("llama-server provider discovery", () => {
       2,
       expect.objectContaining({ profileId: "profile-two" }),
     );
-    expect(resolveLlamaServerDynamicModel(firstCtx)?.name).toBe("org/model:Q4");
-    expect(resolveLlamaServerDynamicModel(secondCtx)?.name).toBe("second scope");
-  });
-
-  it("bounds dynamic model snapshots by scope", async () => {
-    discoverMock.mockResolvedValue(success());
-    const contexts = Array.from(
-      { length: 101 },
-      (_, index) =>
-        ({
-          config: {},
-          provider: "llama-cpp",
-          modelId: "org/model:Q4",
-          modelRegistry: {},
-          agentRuntimeId: `runtime-${index}`,
-          providerConfig: {
-            baseUrl: "http://localhost:8080/v1",
-            api: "openai-completions",
-          },
-        }) as unknown as ProviderPrepareDynamicModelContext,
+    expect(discoverMock).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ apiKey: "first-profile-key" }),
     );
-
-    for (const ctx of contexts) {
-      await prepareLlamaServerDynamicModels(ctx);
-    }
-
-    expect(resolveLlamaServerDynamicModel(contexts[0]!)).toBeUndefined();
-    expect(resolveLlamaServerDynamicModel(contexts.at(-1)!)).toMatchObject({
-      id: "org/model:Q4",
-    });
+    expect(discoverMock).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ apiKey: "second-profile-key" }),
+    );
+    expect(firstModel?.name).toBe("org/model:Q4");
+    expect(secondModel?.name).toBe("second scope");
   });
 
-  it("keeps dynamic snapshots separate when only the endpoint changes", async () => {
+  it("keeps requested models separate when only the endpoint changes", async () => {
     discoverMock.mockResolvedValueOnce(success()).mockResolvedValueOnce({
       ...success(),
       models: [{ ...model(), config: { ...model().config, name: "second endpoint" } }],
     });
     const base = {
-      config: {},
-      provider: "llama-cpp",
-      modelId: "org/model:Q4",
-      modelRegistry: {},
       agentRuntimeId: "endpoint-runtime",
       authProfileId: "endpoint-profile",
     };
-    const first = {
+    const first = dynamicContext({
       ...base,
       providerConfig: { baseUrl: "http://localhost:8080/v1", api: "openai-completions" },
-    } as unknown as ProviderPrepareDynamicModelContext;
-    const second = {
+    });
+    const second = dynamicContext({
       ...base,
       providerConfig: { baseUrl: "http://localhost:8081/v1", api: "openai-completions" },
-    } as unknown as ProviderPrepareDynamicModelContext;
-
-    await prepareLlamaServerDynamicModels(first);
-    await prepareLlamaServerDynamicModels(second);
-
-    expect(resolveLlamaServerDynamicModel(first)?.name).toBe("org/model:Q4");
-    expect(resolveLlamaServerDynamicModel(second)?.name).toBe("second endpoint");
-  });
-
-  it("clears a scope snapshot when its refresh cannot discover the server", async () => {
-    discoverMock.mockResolvedValueOnce(success()).mockResolvedValueOnce({
-      kind: "unreachable",
-      endpoint: { origin: "http://localhost:8080", inferenceBaseUrl: "http://localhost:8080/v1" },
-      error: new Error("offline"),
     });
-    const ctx = {
-      config: {},
-      provider: "llama-cpp",
-      modelId: "org/model:Q4",
-      modelRegistry: {},
-      agentRuntimeId: "failed-refresh-runtime",
-      providerConfig: {
-        baseUrl: "http://localhost:8080/v1",
-        api: "openai-completions",
-      },
-    } as unknown as ProviderPrepareDynamicModelContext;
 
-    await prepareLlamaServerDynamicModels(ctx);
-    expect(resolveLlamaServerDynamicModel(ctx)).toMatchObject({ id: "org/model:Q4" });
-    await prepareLlamaServerDynamicModels(ctx);
-    expect(resolveLlamaServerDynamicModel(ctx)).toBeUndefined();
-  });
+    const firstModel = await prepareLlamaServerDynamicModel(first);
+    const secondModel = await prepareLlamaServerDynamicModel(second);
 
-  it("refreshes and resolves dynamic model ids containing slashes", async () => {
-    discoverMock.mockResolvedValue(success());
-    const ctx = {
-      config: {},
-      provider: "llama-cpp",
-      modelId: "org/model:Q4",
-      modelRegistry: {},
-      providerConfig: {
-        baseUrl: "http://localhost:8080/v1",
-        api: "openai-completions",
-      },
-    } as unknown as ProviderPrepareDynamicModelContext;
-
-    await prepareLlamaServerDynamicModels(ctx);
-
-    expect(resolveLlamaServerDynamicModel(ctx)).toMatchObject({
-      provider: "llama-cpp",
-      id: "org/model:Q4",
+    expect(firstModel).toMatchObject({
+      name: "org/model:Q4",
       baseUrl: "http://localhost:8080/v1",
-      api: "openai-completions",
     });
+    expect(secondModel).toMatchObject({
+      name: "second endpoint",
+      baseUrl: "http://localhost:8081/v1",
+    });
+  });
+
+  it("prefers explicit Authorization over the profile API key during model preparation", async () => {
+    runtimeApiKeyMock.mockResolvedValue("profile-key");
+    discoverMock.mockResolvedValue(success());
+    const headers = { Authorization: "Bearer endpoint-key" };
+
+    await prepareLlamaServerDynamicModel(
+      dynamicContext({
+        providerConfig: { baseUrl: "http://localhost:8080/v1", headers },
+      }),
+    );
+
+    expect(discoverMock).toHaveBeenCalledWith(
+      expect.objectContaining({ apiKey: undefined, headers, cacheTtlMs: 0 }),
+    );
+  });
+
+  it.each([
+    {
+      label: "the server is unavailable",
+      discovery: {
+        kind: "unreachable" as const,
+        endpoint: { origin: "http://localhost:8080", inferenceBaseUrl: "http://localhost:8080/v1" },
+        error: new Error("offline"),
+      },
+    },
+    {
+      label: "the requested model disappears",
+      discovery: { ...success(), models: [] },
+    },
+  ])("returns no stale model when $label", async ({ discovery }) => {
+    discoverMock.mockResolvedValueOnce(success()).mockResolvedValueOnce(discovery);
+    const ctx = dynamicContext({
+      agentRuntimeId: "failed-refresh-runtime",
+    });
+
+    await expect(prepareLlamaServerDynamicModel(ctx)).resolves.toMatchObject({
+      id: "org/model:Q4",
+    });
+    await expect(prepareLlamaServerDynamicModel(ctx)).resolves.toBeUndefined();
   });
 });
diff --git a/extensions/llama-cpp/src/external-server/provider.ts b/extensions/llama-cpp/src/external-server/provider.ts
index 2138214413a2..080d9eb2e73f 100644
--- a/extensions/llama-cpp/src/external-server/provider.ts
+++ b/extensions/llama-cpp/src/external-server/provider.ts
@@ -1,8 +1,6 @@
-import { pruneMapToMaxSize } from "openclaw/plugin-sdk/collection-runtime";
 import type {
   ProviderCatalogContext,
   ProviderPrepareDynamicModelContext,
-  ProviderResolveDynamicModelContext,
   ProviderRuntimeModel,
 } from "openclaw/plugin-sdk/plugin-entry";
 import type { ModelProviderConfig } from "openclaw/plugin-sdk/provider-model-shared";
@@ -14,47 +12,7 @@ import {
 } from "./auth.js";
 import { discoverLlamaServer } from "./discovery.js";
 import { resolveLlamaServerEndpoint } from "./endpoint.js";
-import { buildLlamaServerProviderConfig, type LlamaServerDiscoveredModel } from "./models.js";
-
-const dynamicModels = new Map<string, ProviderRuntimeModel[]>();
-const LLAMA_SERVER_DYNAMIC_MODEL_MAX_SCOPES = 100;
-
-function cacheDynamicModels(key: string, models: ProviderRuntimeModel[]): void {
-  dynamicModels.delete(key);
-  dynamicModels.set(key, models);
-  pruneMapToMaxSize(dynamicModels, LLAMA_SERVER_DYNAMIC_MODEL_MAX_SCOPES);
-}
-
-function dynamicModelScopeKey(
-  ctx: Pick<
-    ProviderResolveDynamicModelContext,
-    "agentRuntimeId" | "agentDir" | "authProfileId" | "providerConfig"
-  >,
-): string {
-  return [
-    ctx.agentRuntimeId ?? ctx.agentDir ?? "",
-    ctx.authProfileId ?? "",
-    ctx.providerConfig?.baseUrl ?? "",
-  ].join("\u0000");
-}
-
-function toRuntimeModel(
-  model: LlamaServerDiscoveredModel,
-  providerConfig: {
-    baseUrl?: string;
-    api?: ProviderRuntimeModel["api"];
-  },
-): ProviderRuntimeModel {
-  return {
-    ...model.config,
-    provider: LLAMA_CPP_PROVIDER_ID,
-    api: providerConfig.api ?? "openai-completions",
-    baseUrl: resolveLlamaServerEndpoint(providerConfig.baseUrl).inferenceBaseUrl,
-    input: model.config.input.filter(
-      (entry): entry is "text" | "image" => entry === "text" || entry === "image",
-    ),
-  };
-}
+import { buildLlamaServerProviderConfig } from "./models.js";
 
 /** Discovers external llama-server models for provider runtime resolution. */
 export async function discoverLlamaServerProvider(
@@ -96,9 +54,9 @@ export async function discoverLlamaServerProvider(
   };
 }
 
-export async function prepareLlamaServerDynamicModels(
+export async function prepareLlamaServerDynamicModel(
   ctx: ProviderPrepareDynamicModelContext,
-): Promise<void> {
+): Promise<ProviderRuntimeModel | undefined> {
   const apiKey = await resolveLlamaServerRuntimeApiKey({
     config: ctx.config,
     agentDir: ctx.agentDir,
@@ -115,19 +73,20 @@ export async function prepareLlamaServerDynamicModels(
     headers,
     cacheTtlMs: 0,
   });
-  const key = dynamicModelScopeKey(ctx);
-  cacheDynamicModels(
-    key,
+  const model =
     discovery.kind === "success"
-      ? discovery.models.map((model) => toRuntimeModel(model, ctx.providerConfig ?? {}))
-      : [],
-  );
-}
-
-export function resolveLlamaServerDynamicModel(
-  params: ProviderResolveDynamicModelContext,
-): ProviderRuntimeModel | undefined {
-  return dynamicModels
-    .get(dynamicModelScopeKey(params))
-    ?.find((model) => model.id === params.modelId);
+      ? discovery.models.find((entry) => entry.config.id === ctx.modelId)
+      : undefined;
+  if (!model) {
+    return undefined;
+  }
+  return {
+    ...model.config,
+    provider: LLAMA_CPP_PROVIDER_ID,
+    api: ctx.providerConfig?.api ?? "openai-completions",
+    baseUrl: resolveLlamaServerEndpoint(ctx.providerConfig?.baseUrl).inferenceBaseUrl,
+    input: model.config.input.filter(
+      (entry): entry is "text" | "image" => entry === "text" || entry === "image",
+    ),
+  };
 }
diff --git a/extensions/llama-cpp/src/managed-provider.ts b/extensions/llama-cpp/src/managed-provider.ts
index 607348df4e2d..0b3f76b67614 100644
--- a/extensions/llama-cpp/src/managed-provider.ts
+++ b/extensions/llama-cpp/src/managed-provider.ts
@@ -21,8 +21,7 @@ import {
 import { normalizeLlamaServerProviderConfig } from "./external-server/endpoint.js";
 import {
   discoverLlamaServerProvider,
-  prepareLlamaServerDynamicModels,
-  resolveLlamaServerDynamicModel,
+  prepareLlamaServerDynamicModel,
 } from "./external-server/provider.js";
 import {
   configureLlamaServerNonInteractive,
@@ -119,15 +118,10 @@ export function registerLlamaCppProvider(api: OpenClawPluginApi): void {
       providerConfig.localService
         ? providerConfig
         : normalizeLlamaServerProviderConfig(providerConfig),
-    prepareDynamicModel: async (ctx) => {
-      if (!ctx.config?.models?.providers?.[LLAMA_CPP_PROVIDER_ID]?.localService) {
-        await prepareLlamaServerDynamicModels(ctx);
-      }
-    },
-    resolveDynamicModel: (ctx) =>
+    prepareDynamicModel: async (ctx) =>
       ctx.config?.models?.providers?.[LLAMA_CPP_PROVIDER_ID]?.localService
         ? undefined
-        : resolveLlamaServerDynamicModel(ctx),
+        : await prepareLlamaServerDynamicModel(ctx),
     wrapStreamFn: (ctx) => {
       const providerConfig = ctx.config?.models?.providers?.[LLAMA_CPP_PROVIDER_ID];
       if (!providerConfig?.localService) {
diff --git a/extensions/lmstudio/api.ts b/extensions/lmstudio/api.ts
index 4b332008df89..ce2cd4d9b5fd 100644
--- a/extensions/lmstudio/api.ts
+++ b/extensions/lmstudio/api.ts
@@ -25,7 +25,7 @@ export {
   normalizeLmstudioConfiguredCatalogEntry,
   normalizeLmstudioProviderConfig,
   prepareAppGuidedLmstudioSetup,
-  prepareLmstudioDynamicModels,
+  prepareLmstudioDynamicModel,
   promptAndConfigureLmstudioInteractive,
   resolveLmstudioConfiguredApiKey,
   resolveLmstudioInferenceBase,
diff --git a/extensions/lmstudio/index.test.ts b/extensions/lmstudio/index.test.ts
index 2cb99c2d52ea..71fa72c9722a 100644
--- a/extensions/lmstudio/index.test.ts
+++ b/extensions/lmstudio/index.test.ts
@@ -1,17 +1,29 @@
 // Lmstudio tests cover index plugin behavior.
-import type { OpenClawConfig, ProviderAuthMethod } from "openclaw/plugin-sdk/plugin-entry";
+import { createDeferred } from "openclaw/plugin-sdk/extension-shared";
+import type {
+  OpenClawConfig,
+  ProviderAuthMethod,
+  ProviderPrepareDynamicModelContext,
+} from "openclaw/plugin-sdk/plugin-entry";
 import { capturePluginRegistration } from "openclaw/plugin-sdk/plugin-test-runtime";
 import { CUSTOM_LOCAL_AUTH_MARKER } from "openclaw/plugin-sdk/provider-auth";
-import type { ModelProviderConfig } from "openclaw/plugin-sdk/provider-model-shared";
+import type {
+  ModelDefinitionConfig,
+  ModelProviderConfig,
+} from "openclaw/plugin-sdk/provider-model-shared";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import plugin from "./index.js";
 import { LMSTUDIO_LOCAL_API_KEY_PLACEHOLDER } from "./src/defaults.js";
 
 const fetchLmstudioModelsMock = vi.hoisted(() => vi.fn());
+const discoverLmstudioModelsMock = vi.hoisted(() =>
+  vi.fn<typeof import("./src/models.fetch.js").discoverLmstudioModels>(),
+);
 
 vi.mock("./src/models.fetch.js", async (importOriginal) => ({
   ...(await importOriginal<typeof import("./src/models.fetch.js")>()),
   fetchLmstudioModels: fetchLmstudioModelsMock,
+  discoverLmstudioModels: discoverLmstudioModelsMock,
 }));
 
 function registerProvider() {
@@ -83,9 +95,42 @@ function createRemoteProviderConfig(overrides?: Partial<ModelProviderConfig>): M
   };
 }
 
+function createDynamicModelContext(
+  profile: "first" | "second",
+): ProviderPrepareDynamicModelContext {
+  return {
+    provider: "lmstudio",
+    modelId: "shared-model",
+    modelRegistry: {
+      getAll: () => [],
+      getAvailable: () => [],
+      find: () => undefined,
+      hasConfiguredAuth: () => false,
+    },
+    authProfileId: `lmstudio:${profile}`,
+    providerConfig: {
+      baseUrl: "http://lmstudio.internal:1234/v1",
+      headers: { Authorization: `Bearer ${profile}-profile` },
+    },
+  };
+}
+
+function createDiscoveredModel(name: string, contextWindow: number): ModelDefinitionConfig {
+  return {
+    id: "shared-model",
+    name,
+    reasoning: false,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow,
+    maxTokens: 8192,
+  };
+}
+
 describe("lmstudio plugin", () => {
   beforeEach(() => {
     fetchLmstudioModelsMock.mockReset();
+    discoverLmstudioModelsMock.mockReset();
   });
 
   it("registers llama.cpp GBNF tool-schema projection", () => {
@@ -95,6 +140,71 @@ describe("lmstudio plugin", () => {
     });
   });
 
+  it("keeps concurrent model preparations isolated when shared-endpoint profiles finish in reverse order", async () => {
+    const provider = registerProvider();
+    const prepareDynamicModel = provider.prepareDynamicModel;
+    if (!prepareDynamicModel) {
+      throw new Error("expected the LM Studio provider to prepare dynamic models");
+    }
+    const firstDiscovery = createDeferred<ModelDefinitionConfig[]>();
+    const secondDiscovery = createDeferred<ModelDefinitionConfig[]>();
+    discoverLmstudioModelsMock.mockImplementation(({ headers }) =>
+      headers?.Authorization === "Bearer first-profile"
+        ? firstDiscovery.promise
+        : secondDiscovery.promise,
+    );
+
+    const firstPreparation = prepareDynamicModel(createDynamicModelContext("first"));
+    const secondPreparation = prepareDynamicModel(createDynamicModelContext("second"));
+    await vi.waitFor(() => expect(discoverLmstudioModelsMock).toHaveBeenCalledTimes(2));
+
+    secondDiscovery.resolve([createDiscoveredModel("Second profile model", 65_536)]);
+    const secondPrepared = await secondPreparation;
+    firstDiscovery.resolve([createDiscoveredModel("First profile model", 32_768)]);
+    const firstPrepared = await firstPreparation;
+
+    expect(secondPrepared).toMatchObject({
+      id: "shared-model",
+      name: "Second profile model",
+      contextWindow: 65_536,
+    });
+    expect(firstPrepared).toMatchObject({
+      id: "shared-model",
+      name: "First profile model",
+      contextWindow: 32_768,
+    });
+  });
+
+  it("returns only the requested discovered model without retaining stale endpoint results", async () => {
+    const provider = registerProvider();
+    const prepareDynamicModel = provider.prepareDynamicModel;
+    if (!prepareDynamicModel) {
+      throw new Error("expected the LM Studio provider to prepare dynamic models");
+    }
+    const otherModel = { ...createDiscoveredModel("Other model", 16_384), id: "other-model" };
+    const requestedModel = createDiscoveredModel("Requested model", 32_768);
+    discoverLmstudioModelsMock
+      .mockResolvedValueOnce([otherModel, requestedModel])
+      .mockResolvedValueOnce([otherModel]);
+
+    const context = createDynamicModelContext("first");
+    await expect(prepareDynamicModel(context)).resolves.toMatchObject({
+      id: "shared-model",
+      name: "Requested model",
+      provider: "lmstudio",
+      api: "openai-completions",
+      baseUrl: "http://lmstudio.internal:1234/v1",
+      contextWindow: 32_768,
+    });
+    await expect(prepareDynamicModel(context)).resolves.toBeUndefined();
+    expect(discoverLmstudioModelsMock).toHaveBeenCalledWith({
+      baseUrl: "http://lmstudio.internal:1234/v1",
+      apiKey: "",
+      headers: { Authorization: "Bearer first-profile" },
+      quiet: true,
+    });
+  });
+
   it("preflights the requested LM Studio model before destructive non-interactive reset", async () => {
     fetchLmstudioModelsMock.mockResolvedValue({
       reachable: true,
diff --git a/extensions/lmstudio/index.ts b/extensions/lmstudio/index.ts
index 5590607b7414..dd21fac56fa6 100644
--- a/extensions/lmstudio/index.ts
+++ b/extensions/lmstudio/index.ts
@@ -8,7 +8,6 @@ import {
   type ProviderAuthMethod,
   type ProviderAuthMethodNonInteractiveContext,
   type ProviderAuthResult,
-  type ProviderRuntimeModel,
 } from "openclaw/plugin-sdk/plugin-entry";
 import {
   CUSTOM_LOCAL_AUTH_MARKER,
@@ -33,8 +32,6 @@ import { shouldUseLmstudioSyntheticAuth } from "./src/provider-auth.js";
 import { wrapLmstudioInferencePreload } from "./src/stream.js";
 
 const PROVIDER_ID = "lmstudio";
-// Intentional: dynamic models are cached per LM Studio endpoint (`baseUrl`) only.
-const cachedDynamicModels = new Map<string, ProviderRuntimeModel[]>();
 
 type LmstudioNonInteractiveValidationContext = Parameters<
   NonNullable<ProviderAuthMethod["validateNonInteractive"]>
@@ -233,15 +230,8 @@ export default definePluginEntry({
       normalizeConfig: ({ providerConfig }) => normalizeLmstudioProviderConfig(providerConfig),
       prepareDynamicModel: async (ctx) => {
         const providerSetup = await loadProviderSetup();
-        cachedDynamicModels.set(
-          ctx.providerConfig?.baseUrl ?? "",
-          await providerSetup.prepareLmstudioDynamicModels(ctx),
-        );
+        return await providerSetup.prepareLmstudioDynamicModel(ctx);
       },
-      resolveDynamicModel: (ctx) =>
-        cachedDynamicModels
-          .get(ctx.providerConfig?.baseUrl ?? "")
-          ?.find((model) => model.id === ctx.modelId),
       augmentModelCatalog: (ctx) => resolveLmstudioAugmentedCatalogEntries(ctx.config),
       wrapStreamFn: wrapLmstudioInferencePreload,
       ...buildProviderToolCompatFamilyHooks("llamacpp-gbnf"),
diff --git a/extensions/lmstudio/src/api.ts b/extensions/lmstudio/src/api.ts
index 730801c24bf4..e601b34351ba 100644
--- a/extensions/lmstudio/src/api.ts
+++ b/extensions/lmstudio/src/api.ts
@@ -40,6 +40,6 @@ export {
   detectAppGuidedLmstudioAvailability,
   discoverLmstudioProvider,
   prepareAppGuidedLmstudioSetup,
-  prepareLmstudioDynamicModels,
+  prepareLmstudioDynamicModel,
   promptAndConfigureLmstudioInteractive,
 } from "./setup.js";
diff --git a/extensions/lmstudio/src/setup.ts b/extensions/lmstudio/src/setup.ts
index 97694a40a82c..4dd8dcbc53ca 100644
--- a/extensions/lmstudio/src/setup.ts
+++ b/extensions/lmstudio/src/setup.ts
@@ -1046,9 +1046,9 @@ export async function discoverLmstudioProvider(ctx: ProviderCatalogContext): Pro
   };
 }
 
-export async function prepareLmstudioDynamicModels(
+export async function prepareLmstudioDynamicModel(
   ctx: ProviderPrepareDynamicModelContext,
-): Promise<ProviderRuntimeModel[]> {
+): Promise<ProviderRuntimeModel | undefined> {
   const baseUrl = resolveLmstudioInferenceBase(ctx.providerConfig?.baseUrl);
   const { apiKey, headers } = await resolveLmstudioRequestContext({
     config: ctx.config,
@@ -1062,15 +1062,18 @@ export async function prepareLmstudioDynamicModels(
     headers,
     quiet: true,
   });
-  return discoveredModels.map((model) =>
-    Object.assign({}, model, {
-      provider: PROVIDER_ID,
-      api: ctx.providerConfig?.api ?? `openai-completions`,
-      baseUrl,
-      input: model.input.filter(
-        (entry): entry is "text" | "image" => entry === "text" || entry === "image",
-      ),
-    }),
-  );
+  const model = discoveredModels.find((candidate) => candidate.id === ctx.modelId);
+  if (!model) {
+    return undefined;
+  }
+  return {
+    ...model,
+    provider: PROVIDER_ID,
+    api: ctx.providerConfig?.api ?? "openai-completions",
+    baseUrl,
+    input: model.input.filter(
+      (entry): entry is "text" | "image" => entry === "text" || entry === "image",
+    ),
+  };
 }
 /* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */
diff --git a/extensions/ollama/index.test.ts b/extensions/ollama/index.test.ts
index 0a20239cf55b..e9175aef0bab 100644
--- a/extensions/ollama/index.test.ts
+++ b/extensions/ollama/index.test.ts
@@ -1084,9 +1084,7 @@ describe("ollama plugin", () => {
     const context = createDynamicModelContext("llama3.2:latest");
 
     try {
-      await provider.prepareDynamicModel?.(context as never);
-
-      const resolved = provider.resolveDynamicModel?.(context as never);
+      const resolved = await provider.prepareDynamicModel?.(context as never);
       expect(resolved?.provider).toBe("ollama");
       expect(resolved?.id).toBe("llama3.2:latest");
       expect(resolved?.api).toBe("ollama");
@@ -1134,9 +1132,7 @@ describe("ollama plugin", () => {
       };
       const context = createDynamicModelContext("qwen3-coder:cloud", config);
 
-      await provider.prepareDynamicModel?.(context as never);
-
-      const resolved = provider.resolveDynamicModel?.(context as never);
+      const resolved = await provider.prepareDynamicModel?.(context as never);
       expect(resolved?.provider).toBe("ollama");
       expect(resolved?.id).toBe("qwen3-coder:cloud");
       expect(resolved?.api).toBe("openai-completions");
@@ -1172,7 +1168,7 @@ describe("ollama plugin", () => {
     mockDiscoveredOllamaProvider([], { baseUrl, once: true });
     const context = createDynamicModelContext("private-dynamic-model", config);
 
-    await provider.prepareDynamicModel?.(context as never);
+    const resolved = await provider.prepareDynamicModel?.(context as never);
 
     expect(buildOllamaProviderMock).toHaveBeenCalledWith(baseUrl, {
       quiet: true,
@@ -1181,10 +1177,10 @@ describe("ollama plugin", () => {
     expect(queryOllamaModelShowInfoMock).toHaveBeenCalledWith(baseUrl, "private-dynamic-model", {
       apiKey: "dynamic-discovery-access",
     });
-    expect(provider.resolveDynamicModel?.(context as never)?.id).toBe("private-dynamic-model");
+    expect(resolved?.id).toBe("private-dynamic-model");
   });
 
-  it("scopes dynamic Ollama model caches to the effective credential", async () => {
+  it("returns the exact prepared Ollama model for concurrent credential profiles", async () => {
     const provider = registerProvider();
     const baseUrl = "https://shared-dynamic-ollama.example.com";
     const modelId = "tenant-dynamic-model";
@@ -1197,25 +1193,34 @@ describe("ollama plugin", () => {
     });
     const discoveredFor = (name: string) => ({
       baseUrl,
-      api: "ollama",
+      api: "ollama" as const,
       models: [{ id: modelId, name, contextWindow: 8192, maxTokens: 2048 }],
     });
-    buildOllamaProviderMock
-      .mockResolvedValueOnce(discoveredFor("First tenant model"))
-      .mockResolvedValueOnce(discoveredFor("Second tenant model"));
+    const completeDiscovery: Array<(result: ReturnType<typeof discoveredFor>) => void> = [];
+    buildOllamaProviderMock.mockImplementation(
+      () =>
+        new Promise<ReturnType<typeof discoveredFor>>((resolve) => {
+          completeDiscovery.push(resolve);
+        }),
+    );
 
-    for (const config of [configFor("first-tenant-access"), configFor("second-tenant-access")]) {
-      await provider.prepareDynamicModel?.(createDynamicModelContext(modelId, config) as never);
-    }
+    const prepareFor = (apiKey: string, authProfileId: string) =>
+      provider.prepareDynamicModel?.({
+        ...createDynamicModelContext(modelId, configFor(apiKey)),
+        authProfileId,
+      } as never);
+    const firstPrepared = prepareFor("first-tenant-access", "ollama:first");
+    const secondPrepared = prepareFor("second-tenant-access", "ollama:second");
 
-    const resolveFor = (apiKey: string) =>
-      provider.resolveDynamicModel?.(
-        createDynamicModelContext(modelId, configFor(apiKey)) as never,
-      );
+    await vi.waitFor(() => expect(buildOllamaProviderMock).toHaveBeenCalledTimes(2));
+    completeDiscovery[1]?.(discoveredFor("Second tenant model"));
+    await expect(secondPrepared).resolves.toMatchObject({
+      id: modelId,
+      name: "Second tenant model",
+    });
+    completeDiscovery[0]?.(discoveredFor("First tenant model"));
+    await expect(firstPrepared).resolves.toMatchObject({ id: modelId, name: "First tenant model" });
 
-    expect(resolveFor("first-tenant-access")?.name).toBe("First tenant model");
-    expect(resolveFor("second-tenant-access")?.name).toBe("Second tenant model");
-    expect(resolveFor("unprepared-tenant-access")).toBeUndefined();
     expect(buildOllamaProviderMock).toHaveBeenNthCalledWith(1, baseUrl, {
       quiet: true,
       apiKey: "first-tenant-access",
@@ -1250,8 +1255,9 @@ describe("ollama plugin", () => {
       const context = createDynamicModelContext("secretref-dynamic-model", config);
 
       try {
-        await provider.prepareDynamicModel?.(context as never);
+        const resolved = await provider.prepareDynamicModel?.(context as never);
 
+        expect(resolved?.id).toBe("secretref-dynamic-model");
         expect(buildOllamaProviderMock).toHaveBeenCalledWith(baseUrl, {
           quiet: true,
           apiKey: secretValue,
@@ -1290,7 +1296,7 @@ describe("ollama plugin", () => {
     });
 
     try {
-      await provider.prepareDynamicModel?.(context as never);
+      await expect(provider.prepareDynamicModel?.(context as never)).resolves.toBeUndefined();
 
       expect(buildOllamaProviderMock).not.toHaveBeenCalled();
       expect(queryOllamaModelShowInfoMock).not.toHaveBeenCalled();
@@ -1301,7 +1307,7 @@ describe("ollama plugin", () => {
     }
   });
 
-  it("invalidates managed dynamic model caches when their SecretRef stops resolving", async () => {
+  it("keeps rotated managed SecretRefs request-owned and fails closed when unavailable", async () => {
     const provider = registerProvider();
     const baseUrl = "https://managed-dynamic-ollama.example.com";
     const modelId = "managed-private-model";
@@ -1319,20 +1325,32 @@ describe("ollama plugin", () => {
     };
     resolveConfiguredSecretInputStringMock
       .mockResolvedValueOnce({ value: "managed-dynamic-access" })
+      .mockResolvedValueOnce({ value: "rotated-managed-access" })
       .mockResolvedValueOnce({ unresolvedRefReason: "managed credential is unavailable" });
     mockDiscoveredOllamaProvider(
       [{ id: modelId, name: "Managed private model", contextWindow: 8192 }],
       { baseUrl, once: true },
     );
+    mockDiscoveredOllamaProvider(
+      [{ id: modelId, name: "Rotated managed model", contextWindow: 8192 }],
+      { baseUrl, once: true },
+    );
     const context = createDynamicModelContext(modelId, config);
 
-    await provider.prepareDynamicModel?.(context as never);
-    expect(provider.resolveDynamicModel?.(context as never)?.id).toBe(modelId);
-
-    await provider.prepareDynamicModel?.(context as never);
-
-    expect(provider.resolveDynamicModel?.(context as never)).toBeUndefined();
-    expect(buildOllamaProviderMock).toHaveBeenCalledOnce();
+    await expect(provider.prepareDynamicModel?.(context as never)).resolves.toMatchObject({
+      id: modelId,
+      name: "Managed private model",
+    });
+    await expect(provider.prepareDynamicModel?.(context as never)).resolves.toMatchObject({
+      id: modelId,
+      name: "Rotated managed model",
+    });
+    await expect(provider.prepareDynamicModel?.(context as never)).resolves.toBeUndefined();
+    expect(buildOllamaProviderMock).toHaveBeenNthCalledWith(2, baseUrl, {
+      quiet: true,
+      apiKey: "rotated-managed-access",
+    });
+    expect(buildOllamaProviderMock).toHaveBeenCalledTimes(2);
   });
 
   it("isolates identically named managed SecretRefs by their resolved configuration", async () => {
@@ -1371,15 +1389,11 @@ describe("ollama plugin", () => {
     );
     const contextFor = (config: typeof firstConfig) => createDynamicModelContext(modelId, config);
 
-    await provider.prepareDynamicModel?.(contextFor(firstConfig) as never);
-    await provider.prepareDynamicModel?.(contextFor(secondConfig) as never);
+    const firstModel = await provider.prepareDynamicModel?.(contextFor(firstConfig) as never);
+    const secondModel = await provider.prepareDynamicModel?.(contextFor(secondConfig) as never);
 
-    expect(provider.resolveDynamicModel?.(contextFor(firstConfig) as never)?.name).toBe(
-      "First managed tenant model",
-    );
-    expect(provider.resolveDynamicModel?.(contextFor(secondConfig) as never)?.name).toBe(
-      "Second managed tenant model",
-    );
+    expect(firstModel?.name).toBe("First managed tenant model");
+    expect(secondModel?.name).toBe("Second managed tenant model");
     expect(buildOllamaProviderMock).toHaveBeenNthCalledWith(1, baseUrl, {
       quiet: true,
       apiKey: "first-managed-tenant-access",
@@ -1412,13 +1426,12 @@ describe("ollama plugin", () => {
     const context = createDynamicModelContext("deepseek-v4-pro:cloud");
 
     try {
-      await provider.prepareDynamicModel?.(context as never);
+      const resolved = await provider.prepareDynamicModel?.(context as never);
 
       expect(queryOllamaModelShowInfoMock).toHaveBeenCalledWith(
         "http://127.0.0.1:11434",
         "deepseek-v4-pro:cloud",
       );
-      const resolved = provider.resolveDynamicModel?.(context as never);
       expect(resolved?.provider).toBe("ollama");
       expect(resolved?.id).toBe("deepseek-v4-pro:cloud");
       expect(resolved?.api).toBe("ollama");
@@ -1971,9 +1984,7 @@ describe("ollama plugin", () => {
     const context = createDynamicModelContext("depseek-v4-pro:cloud");
 
     try {
-      await provider.prepareDynamicModel?.(context as never);
-
-      expect(provider.resolveDynamicModel?.(context as never)).toBeUndefined();
+      await expect(provider.prepareDynamicModel?.(context as never)).resolves.toBeUndefined();
     } finally {
       if (previous === undefined) {
         delete process.env.OLLAMA_API_KEY;
diff --git a/extensions/ollama/index.ts b/extensions/ollama/index.ts
index 9fb7b6c74ab4..40dd4356de03 100644
--- a/extensions/ollama/index.ts
+++ b/extensions/ollama/index.ts
@@ -1,5 +1,4 @@
 // Ollama plugin entrypoint registers its OpenClaw integration.
-import { createHash } from "node:crypto";
 import { collectConfiguredModelRefValues } from "@openclaw/model-catalog-core/configured-model-refs";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
 import { createLazyRuntimeModule } from "openclaw/plugin-sdk/lazy-runtime";
@@ -161,8 +160,6 @@ function classifyOllamaFailoverReason(errorMessage: string): "server_error" | un
   return errorMessage.trim() === OLLAMA_INCOMPLETE_STREAM_ERROR ? "server_error" : undefined;
 }
 
-const dynamicModelCache = new Map<string, ProviderRuntimeModel[]>();
-const dynamicManagedCredentialFingerprints = new WeakMap<OpenClawConfig, Map<string, string>>();
 const OLLAMA_CLOUD_DEFAULT_MODEL_REF = `${OLLAMA_CLOUD_PROVIDER_ID}/${OLLAMA_CLOUD_DEFAULT_MODELS[0].id}`;
 const OLLAMA_CONFIGURED_SHOW_CONCURRENCY = 4;
 const OLLAMA_CONFIGURED_SHOW_MAX_MODELS = 8;
@@ -426,44 +423,6 @@ async function discoverAppGuidedOllamaModel(
   };
 }
 
-function buildDynamicManagedSecretScope(
-  provider: string,
-  baseUrl: string | undefined,
-  configuredApiKey: unknown,
-): string | undefined {
-  const secretRef = coerceSecretRef(configuredApiKey);
-  if (!secretRef || secretRef.source === "env") {
-    return undefined;
-  }
-  return `${provider}\0${resolveOllamaApiBase(baseUrl)}\0${secretRef.source}\0${secretRef.provider}\0${secretRef.id}`;
-}
-
-function buildDynamicCacheKey(
-  provider: string,
-  baseUrl: string | undefined,
-  configuredApiKey: unknown,
-  config?: OpenClawConfig,
-): string {
-  const secretRef = coerceSecretRef(configuredApiKey);
-  const managedSecretScope = buildDynamicManagedSecretScope(provider, baseUrl, configuredApiKey);
-  const apiKey = readUsableOllamaShowApiKey({
-    env: process.env,
-    allowAmbientEnvFallback: !isLocalOllamaBaseUrl(baseUrl),
-    explicitApiKey: configuredApiKey,
-  });
-  // Managed secrets resolve asynchronously; retain their resolved fingerprint
-  // per config so synchronous lookups cannot cross secret-provider ownership.
-  const managedCredentialFingerprint =
-    managedSecretScope && config
-      ? dynamicManagedCredentialFingerprints.get(config)?.get(managedSecretScope)
-      : undefined;
-  const credentialScope =
-    apiKey ?? (secretRef ? `${secretRef.source}\0${secretRef.provider}\0${secretRef.id}` : "");
-  const credentialFingerprint =
-    managedCredentialFingerprint ?? createHash("sha256").update(credentialScope).digest("hex");
-  return `${provider}\0${resolveOllamaApiBase(baseUrl)}\0${credentialFingerprint}`;
-}
-
 function hasOllamaDiscoverySignal(providerConfig: ModelProviderConfig | undefined): boolean {
   return (
     Boolean(process.env.OLLAMA_API_KEY?.trim()) ||
@@ -1173,20 +1132,9 @@ export default definePluginEntry({
           providerId: ctx.provider,
         });
         if (!hasOllamaDiscoverySignal(providerConfig)) {
-          return;
+          return undefined;
         }
         const baseUrl = readProviderBaseUrl(providerConfig);
-        const managedSecretScope = buildDynamicManagedSecretScope(
-          ctx.provider,
-          baseUrl,
-          providerConfig?.apiKey,
-        );
-        let dynamicCacheKey = buildDynamicCacheKey(
-          ctx.provider,
-          baseUrl,
-          providerConfig?.apiKey,
-          ctx.config,
-        );
         let discoveryApiKey: string | undefined;
         if (providerConfig?.apiKey !== undefined && providerConfig.apiKey !== null) {
           const resolved = await resolveConfiguredSecretInputString({
@@ -1197,11 +1145,7 @@ export default definePluginEntry({
             unresolvedReasonStyle: "detailed",
           });
           if (resolved.unresolvedRefReason) {
-            dynamicModelCache.delete(dynamicCacheKey);
-            if (managedSecretScope && ctx.config) {
-              dynamicManagedCredentialFingerprints.get(ctx.config)?.delete(managedSecretScope);
-            }
-            return;
+            return undefined;
           }
           const resolvedApiKey = readConfiguredOllamaApiKey(resolved.value);
           const configuredSecretRef = coerceSecretRef(providerConfig.apiKey);
@@ -1211,38 +1155,11 @@ export default definePluginEntry({
               ? readConcreteOllamaApiKey(process.env.OLLAMA_API_KEY)
               : readConcreteOllamaApiKey(resolvedApiKey);
           if (configuredSecretRef && !discoveryApiKey) {
-            dynamicModelCache.delete(dynamicCacheKey);
-            if (managedSecretScope && ctx.config) {
-              dynamicManagedCredentialFingerprints.get(ctx.config)?.delete(managedSecretScope);
-            }
-            return;
+            return undefined;
           }
         } else if (!isLocalOllamaBaseUrl(baseUrl)) {
           discoveryApiKey = readConcreteOllamaApiKey(process.env.OLLAMA_API_KEY);
         }
-        if (managedSecretScope && ctx.config && discoveryApiKey) {
-          let fingerprints = dynamicManagedCredentialFingerprints.get(ctx.config);
-          if (!fingerprints) {
-            fingerprints = new Map();
-            dynamicManagedCredentialFingerprints.set(ctx.config, fingerprints);
-          }
-          const resolvedCredentialFingerprint = createHash("sha256")
-            .update(discoveryApiKey)
-            .digest("hex");
-          if (
-            fingerprints.has(managedSecretScope) &&
-            fingerprints.get(managedSecretScope) !== resolvedCredentialFingerprint
-          ) {
-            dynamicModelCache.delete(dynamicCacheKey);
-          }
-          fingerprints.set(managedSecretScope, resolvedCredentialFingerprint);
-          dynamicCacheKey = buildDynamicCacheKey(
-            ctx.provider,
-            baseUrl,
-            providerConfig?.apiKey,
-            ctx.config,
-          );
-        }
         const provider = await buildLocalOllamaProvider(baseUrl, {
           quiet: true,
           ...(discoveryApiKey ? { apiKey: discoveryApiKey } : {}),
@@ -1257,42 +1174,21 @@ export default definePluginEntry({
           }),
           api: dynamicApi,
         };
-        const dynamicModels = (dynamicProvider.models ?? []).map((model) =>
-          toDynamicOllamaModel({
+        const discoveredModel = dynamicProvider.models?.find((model) => model.id === ctx.modelId);
+        if (discoveredModel) {
+          return toDynamicOllamaModel({
             provider: ctx.provider,
             providerConfig: dynamicProvider,
-            model,
-          }),
-        );
-        if (!dynamicModels.some((model) => model.id === ctx.modelId)) {
-          const requestedModel = await resolveRequestedDynamicOllamaModel({
-            provider: ctx.provider,
-            providerConfig: dynamicProvider,
-            modelId: ctx.modelId,
-            showApiKey: discoveryApiKey,
-            capContextTokens: true,
+            model: discoveredModel,
           });
-          if (requestedModel) {
-            dynamicModels.push(requestedModel);
-          }
         }
-        dynamicModelCache.set(dynamicCacheKey, dynamicModels);
-      },
-      resolveDynamicModel: (ctx) => {
-        const providerConfig = resolveConfiguredOllamaProviderConfig({
-          config: ctx.config,
-          providerId: ctx.provider,
+        return await resolveRequestedDynamicOllamaModel({
+          provider: ctx.provider,
+          providerConfig: dynamicProvider,
+          modelId: ctx.modelId,
+          showApiKey: discoveryApiKey,
+          capContextTokens: true,
         });
-        return dynamicModelCache
-          .get(
-            buildDynamicCacheKey(
-              ctx.provider,
-              readProviderBaseUrl(providerConfig),
-              providerConfig?.apiKey,
-              ctx.config,
-            ),
-          )
-          ?.find((model) => model.id === ctx.modelId);
       },
       buildUnknownModelHint: () =>
         "Ollama requires authentication to be registered as a provider. " +
diff --git a/src/agents/embedded-agent-runner/model.provider-hooks.ts b/src/agents/embedded-agent-runner/model.provider-hooks.ts
index d14434bd96a4..9db8ae68b063 100644
--- a/src/agents/embedded-agent-runner/model.provider-hooks.ts
+++ b/src/agents/embedded-agent-runner/model.provider-hooks.ts
@@ -29,7 +29,7 @@ export type ProviderRuntimeHooks = {
   ) => string | undefined;
   prepareProviderDynamicModel: (
     params: Parameters<typeof prepareProviderDynamicModel>[0],
-  ) => Promise<void>;
+  ) => ReturnType<typeof prepareProviderDynamicModel>;
   runProviderDynamicModel: (params: Parameters<typeof runProviderDynamicModel>[0]) => unknown;
   shouldPreferProviderRuntimeResolvedModel?: (
     params: Parameters<typeof shouldPreferProviderRuntimeResolvedModel>[0],
diff --git a/src/agents/embedded-agent-runner/model.registry-resolution.ts b/src/agents/embedded-agent-runner/model.registry-resolution.ts
index ba3127181b09..b3829a4a3bb5 100644
--- a/src/agents/embedded-agent-runner/model.registry-resolution.ts
+++ b/src/agents/embedded-agent-runner/model.registry-resolution.ts
@@ -2,6 +2,7 @@ import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { ModelRegistry as CoreModelRegistry } from "../../llm/model-registry.js";
 import type { Model } from "../../llm/types.js";
 import type { PluginMetadataSnapshotOwnerMaps } from "../../plugins/plugin-metadata-snapshot.types.js";
+import type { ProviderRuntimeModel } from "../../plugins/provider-runtime-model.types.js";
 import { ensureAuthProfileStore, resolveAuthProfileOrder } from "../auth-profiles.js";
 import type { AuthProfileCredential } from "../auth-profiles/types.js";
 import { resolveAgentHarnessPolicy } from "../harness/policy.js";
@@ -252,21 +253,9 @@ export function resolveDynamicModelAuthProfile(params: {
   };
 }
 
-function resolvePluginDynamicModelWithRegistry(params: {
-  provider: string;
-  modelId: string;
-  modelRegistry: CoreModelRegistry;
-  cfg?: OpenClawConfig;
-  agentDir?: string;
-  agentRuntimeId?: string;
-  manifestAlias: ManifestModelCatalogProviderAliasMetadata;
-  workspaceDir?: string;
-  authProfileId?: string;
-  authProfileMode?: AuthProfileCredential["type"] | "aws-sdk";
-  preferredProfile?: string;
-  runtimeHooks?: ProviderRuntimeHooks;
-  getStaticCatalogModel?: () => StaticCatalogFallbackModel | undefined;
-}): Model | undefined {
+function resolvePluginDynamicModelWithRegistry(
+  params: ResolveModelWithPreparedRegistryParams,
+): Model | undefined {
   const { provider, modelId, modelRegistry, cfg, agentDir, workspaceDir } = params;
   const runtimeHooks = params.runtimeHooks ?? DEFAULT_PROVIDER_RUNTIME_HOOKS;
   const providerConfig = resolveConfiguredProviderConfig(cfg, provider);
@@ -294,22 +283,24 @@ function resolvePluginDynamicModelWithRegistry(params: {
     workspaceDir,
     runtimeHooks,
   });
-  const pluginDynamicModel = runtimeHooks.runProviderDynamicModel({
-    provider,
-    config: cfg,
-    workspaceDir,
-    context: {
-      config: cfg,
-      agentDir,
-      workspaceDir,
-      ...(agentRuntimeId ? { agentRuntimeId } : {}),
+  const pluginDynamicModel =
+    params.preparedDynamicModel ??
+    (runtimeHooks.runProviderDynamicModel({
       provider,
-      modelId,
-      modelRegistry,
-      providerConfig,
-      ...authProfile,
-    },
-  }) as Model | undefined;
+      config: cfg,
+      workspaceDir,
+      context: {
+        config: cfg,
+        agentDir,
+        workspaceDir,
+        ...(agentRuntimeId ? { agentRuntimeId } : {}),
+        provider,
+        modelId,
+        modelRegistry,
+        providerConfig,
+        ...authProfile,
+      },
+    }) as ProviderRuntimeModel | undefined);
   if (!pluginDynamicModel) {
     return undefined;
   }
@@ -425,6 +416,7 @@ type ResolveModelWithRegistryParams = {
 
 type ResolveModelWithPreparedRegistryParams = ResolveModelWithRegistryParams & {
   manifestAlias: ManifestModelCatalogProviderAliasMetadata;
+  preparedDynamicModel?: ProviderRuntimeModel;
   getStaticCatalogModel?: () => StaticCatalogFallbackModel | undefined;
 };
 
diff --git a/src/agents/embedded-agent-runner/model.test.ts b/src/agents/embedded-agent-runner/model.test.ts
index 20a9ddd3d141..660170d93523 100644
--- a/src/agents/embedded-agent-runner/model.test.ts
+++ b/src/agents/embedded-agent-runner/model.test.ts
@@ -582,6 +582,127 @@ function makeVllmQwenConfig(
 }
 
 describe("resolveModel", () => {
+  it("consumes a directly prepared model through configured overrides and normalization", async () => {
+    const preparedModel = {
+      ...makeModel("prepared-model"),
+      provider: "acme",
+      name: "Prepared Model",
+      api: "openai-completions" as const,
+      baseUrl: "https://discovered.example/v1",
+      input: ["text" as const],
+      contextWindow: 65_536,
+      maxTokens: 8_192,
+    };
+    const prepareProviderDynamicModel = vi.fn(async () => preparedModel);
+    const runProviderDynamicModel = vi.fn(() => undefined);
+    const normalizeProviderResolvedModelWithPlugin = vi.fn(
+      ({ context }: { context: { model: Model } }) => ({
+        ...context.model,
+        name: "Normalized Prepared Model",
+      }),
+    );
+    const cfg = makeProviderConfig("acme", {
+      api: "openai-responses",
+      baseUrl: "https://configured.example/v1",
+      headers: { "X-Tenant": "tenant-a" },
+    });
+
+    const result = await resolveModelAsync("acme", "prepared-model", "/tmp/agent", cfg, {
+      runtimeHooks: {
+        ...createRuntimeHooks(),
+        prepareProviderDynamicModel,
+        runProviderDynamicModel,
+        normalizeProviderResolvedModelWithPlugin,
+      },
+      skipAgentDiscovery: true,
+    });
+
+    expectRecordFields(expectResolvedModel(result), {
+      provider: "acme",
+      id: "prepared-model",
+      name: "Normalized Prepared Model",
+      api: "openai-responses",
+      baseUrl: "https://configured.example/v1",
+      contextWindow: 65_536,
+      maxTokens: 8_192,
+    });
+    expect(expectResolvedModel(result).headers).toEqual(
+      expect.objectContaining({ "X-Tenant": "tenant-a" }),
+    );
+    expect(prepareProviderDynamicModel).toHaveBeenCalledOnce();
+    expect(normalizeProviderResolvedModelWithPlugin).toHaveBeenCalledOnce();
+    expect(runProviderDynamicModel).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    {
+      description: "keeps explicit configured models ahead of prepared models",
+      preferRuntime: false,
+      expectedName: "Configured Model",
+      expectedPreparationCount: 0,
+    },
+    {
+      description: "preserves manually configured limits during runtime comparison",
+      preferRuntime: true,
+      expectedName: "Prepared Model",
+      expectedPreparationCount: 1,
+    },
+    {
+      description: "replaces models-add metadata with a preferred prepared model",
+      preferRuntime: true,
+      metadataSource: "models-add" as const,
+      expectedName: "Prepared Model",
+      expectedPreparationCount: 1,
+    },
+  ])(
+    "$description",
+    async ({ preferRuntime, metadataSource, expectedName, expectedPreparationCount }) => {
+      const prepareProviderDynamicModel = vi.fn(async () => ({
+        ...makeModel("prepared-model"),
+        provider: "acme",
+        name: "Prepared Model",
+        api: "openai-completions" as const,
+        baseUrl: "https://discovered.example/v1",
+        input: ["text" as const],
+        contextWindow: 65_536,
+        maxTokens: 8_192,
+      }));
+      const runProviderDynamicModel = vi.fn(() => undefined);
+      const cfg = makeProviderConfig("acme", {
+        api: "openai-responses",
+        baseUrl: "https://configured.example/v1",
+        models: [
+          {
+            ...makeModel("prepared-model"),
+            name: "Configured Model",
+            contextWindow: 32_768,
+            maxTokens: 4_096,
+            ...(metadataSource ? { metadataSource } : {}),
+          },
+        ],
+      });
+
+      const result = await resolveModelAsync("acme", "prepared-model", "/tmp/agent", cfg, {
+        runtimeHooks: {
+          ...createRuntimeHooks(),
+          prepareProviderDynamicModel,
+          runProviderDynamicModel,
+          shouldPreferProviderRuntimeResolvedModel: () => preferRuntime,
+        },
+        skipAgentDiscovery: true,
+      });
+
+      expectRecordFields(expectResolvedModel(result), {
+        name: expectedName,
+        api: "openai-responses",
+        baseUrl: "https://configured.example/v1",
+        contextWindow: metadataSource ? 65_536 : 32_768,
+      });
+      expect(prepareProviderDynamicModel).toHaveBeenCalledTimes(expectedPreparationCount);
+      expect(runProviderDynamicModel).not.toHaveBeenCalled();
+    },
+  );
+
   it("reuses agent discovery stores while the agent model files are unchanged", async () => {
     mockModelDiscovery();
 
diff --git a/src/agents/embedded-agent-runner/model.ts b/src/agents/embedded-agent-runner/model.ts
index 9b8c32722088..b65e4ddd80d8 100644
--- a/src/agents/embedded-agent-runner/model.ts
+++ b/src/agents/embedded-agent-runner/model.ts
@@ -419,7 +419,7 @@ export async function resolveModelAsync(
       });
     };
     const resolveDynamicAttempt = async () => {
-      await runtimeHooks.prepareProviderDynamicModel({
+      const preparedDynamicModel = await runtimeHooks.prepareProviderDynamicModel({
         provider: normalizedRef.provider,
         config: cfg,
         workspaceDir,
@@ -448,6 +448,7 @@ export async function resolveModelAsync(
         authProfileMode: options?.authProfileMode,
         preferredProfile: options?.preferredProfile,
         runtimeHooks,
+        ...(preparedDynamicModel ? { preparedDynamicModel } : {}),
         getStaticCatalogModel: getManifestStaticCatalogModel,
         ...(options?.allowBundledStaticCatalogFallback ? { skipConfiguredFallback: true } : {}),
       });
diff --git a/src/agents/live-model-dynamic-candidates.test.ts b/src/agents/live-model-dynamic-candidates.test.ts
index 8bbe6b37bd0d..952b2928fc7a 100644
--- a/src/agents/live-model-dynamic-candidates.test.ts
+++ b/src/agents/live-model-dynamic-candidates.test.ts
@@ -155,6 +155,27 @@ describe("appendPrioritizedDynamicLiveModels", () => {
     expect(resolveDynamicModel).not.toHaveBeenCalled();
   });
 
+  it("materializes a directly prepared model without retrying synchronous resolution", async () => {
+    const preparedModel = model(DYNAMIC_PROVIDER, "glm-5");
+    providerRuntimeMocks.prepareProviderDynamicModel.mockResolvedValue(preparedModel);
+
+    const result = await appendPrioritizedDynamicLiveModels({
+      models: [],
+      agentDir: "/tmp/openclaw-agent",
+      modelRegistry: REGISTRY,
+      refs: [{ provider: DYNAMIC_PROVIDER, id: "glm-5" }],
+    });
+
+    expect(result.added).toEqual([preparedModel]);
+    expect(providerRuntimeMocks.prepareProviderDynamicModel).toHaveBeenCalledOnce();
+    expect(providerRuntimeMocks.runProviderDynamicModel).not.toHaveBeenCalled();
+    expect(normalizeDiscoveredAgentModelMock).toHaveBeenCalledWith(
+      preparedModel,
+      "/tmp/openclaw-agent",
+      { config: undefined, workspaceDir: undefined },
+    );
+  });
+
   it("uses default provider runtime hooks when resolvers are not injected", async () => {
     providerRuntimeMocks.runProviderDynamicModel.mockImplementation((params) =>
       params.context.provider === DYNAMIC_PROVIDER && params.context.modelId === "glm-5"
diff --git a/src/agents/test-helpers/live-model-dynamic-candidates.ts b/src/agents/test-helpers/live-model-dynamic-candidates.ts
index a1a827899266..f41c2438bc1c 100644
--- a/src/agents/test-helpers/live-model-dynamic-candidates.ts
+++ b/src/agents/test-helpers/live-model-dynamic-candidates.ts
@@ -29,9 +29,9 @@ const providerRuntimeLoader = createLazyImportLoader<ProviderRuntimeModule>(
 
 async function prepareProviderDynamicModelDefault(
   params: Parameters<DynamicModelPreparer>[0],
-): Promise<void> {
+): ReturnType<DynamicModelPreparer> {
   const { prepareProviderDynamicModel } = await providerRuntimeLoader.load();
-  await prepareProviderDynamicModel(params);
+  return await prepareProviderDynamicModel(params);
 }
 
 async function runProviderDynamicModelDefault(
@@ -108,20 +108,22 @@ export async function appendPrioritizedDynamicLiveModels(params: {
       modelRegistry: params.modelRegistry,
       providerConfig,
     };
-    await prepareDynamicModel({
-      provider: ref.provider,
-      config: params.config,
-      workspaceDir: params.workspaceDir,
-      env: params.env,
-      context,
-    });
-    const resolved = await resolveDynamicModel({
+    const prepared = await prepareDynamicModel({
       provider: ref.provider,
       config: params.config,
       workspaceDir: params.workspaceDir,
       env: params.env,
       context,
     });
+    const resolved =
+      prepared ??
+      (await resolveDynamicModel({
+        provider: ref.provider,
+        config: params.config,
+        workspaceDir: params.workspaceDir,
+        env: params.env,
+        context,
+      }));
     if (!resolved) {
       continue;
     }
diff --git a/src/plugins/provider-plugin.types.ts b/src/plugins/provider-plugin.types.ts
index f8a512b37d50..d7917bdf6b3c 100644
--- a/src/plugins/provider-plugin.types.ts
+++ b/src/plugins/provider-plugin.types.ts
@@ -154,19 +154,21 @@ export type ProviderPlugin = {
    * 3. core fallback heuristics
    * 4. generic provider-config fallback
    *
-   * Keep this hook cheap and deterministic. If you need network I/O first, use
-   * `prepareDynamicModel` to prime state for the async retry path.
+   * Keep this hook cheap and deterministic. Async model discovery belongs in
+   * `prepareDynamicModel`, which can return the prepared model directly.
    */
   resolveDynamicModel?: (
     ctx: ProviderResolveDynamicModelContext,
   ) => ProviderRuntimeModel | null | undefined;
   /**
-   * Optional async prefetch for dynamic model resolution.
+   * Optional async preparation for dynamic model resolution.
    *
-   * OpenClaw calls this only from async model resolution paths. After it
-   * completes, `resolveDynamicModel` is called again.
+   * OpenClaw calls this only from async model resolution paths. Return the
+   * requested model directly, or return nothing to retry `resolveDynamicModel`.
    */
-  prepareDynamicModel?: (ctx: ProviderPrepareDynamicModelContext) => Promise<void>;
+  prepareDynamicModel?: (
+    ctx: ProviderPrepareDynamicModelContext,
+  ) => Promise<ProviderRuntimeModel | void>;
   /**
    * Lets a provider plugin opt exact configured models into a runtime
    * metadata comparison pass before the embedded runner returns the explicit
diff --git a/src/plugins/provider-runtime.test.ts b/src/plugins/provider-runtime.test.ts
index 0bd99bdcfb81..7f6c96232ed9 100644
--- a/src/plugins/provider-runtime.test.ts
+++ b/src/plugins/provider-runtime.test.ts
@@ -2041,7 +2041,7 @@ describe("provider-runtime", () => {
       { pluginId: "demo", providerIds: ["demo"] },
     ]);
     resolveExternalAuthProfileProviderPluginIdsMock.mockReturnValue(["demo"]);
-    const prepareDynamicModel = vi.fn(async () => undefined);
+    const prepareDynamicModel = vi.fn(async () => MODEL);
     const createStreamFn = vi.fn(() => vi.fn());
     const sanitizeReplayHistory = vi.fn(
       async ({
@@ -2245,12 +2245,14 @@ describe("provider-runtime", () => {
       }),
     ).toBe("DEMO_PROFILE");
 
-    await prepareProviderDynamicModel({
-      provider: DEMO_PROVIDER_ID,
-      context: createDemoRuntimeContext({
-        modelRegistry: EMPTY_MODEL_REGISTRY,
+    expect(
+      await prepareProviderDynamicModel({
+        provider: DEMO_PROVIDER_ID,
+        context: createDemoRuntimeContext({
+          modelRegistry: EMPTY_MODEL_REGISTRY,
+        }),
       }),
-    });
+    ).toEqual(MODEL);
 
     expect(
       resolveProviderReasoningOutputModeWithPlugin({
diff --git a/src/plugins/provider-runtime.ts b/src/plugins/provider-runtime.ts
index 317513de30c9..2fd908939b83 100644
--- a/src/plugins/provider-runtime.ts
+++ b/src/plugins/provider-runtime.ts
@@ -282,8 +282,8 @@ export async function prepareProviderDynamicModel(params: {
   workspaceDir?: string;
   env?: NodeJS.ProcessEnv;
   context: ProviderPrepareDynamicModelContext;
-}): Promise<void> {
-  await resolveProviderRuntimePlugin(params)?.prepareDynamicModel?.(params.context);
+}): Promise<ProviderRuntimeModel | void> {
+  return resolveProviderRuntimePlugin(params)?.prepareDynamicModel?.(params.context);
 }
 
 export function shouldPreferProviderRuntimeResolvedModel(params: {
diff --git a/src/plugins/provider-runtime.types.ts b/src/plugins/provider-runtime.types.ts
index 53af7112504f..77a76dc20363 100644
--- a/src/plugins/provider-runtime.types.ts
+++ b/src/plugins/provider-runtime.types.ts
@@ -41,11 +41,10 @@ export type ProviderResolveDynamicModelContext = {
 };
 
 /**
- * Optional async warm-up for dynamic model resolution.
+ * Optional async preparation for dynamic model resolution.
  *
- * Called only from async model resolution paths, before retrying
- * `resolveDynamicModel`. This is the place to refresh caches or fetch provider
- * metadata over the network.
+ * Called only from async model resolution paths. Providers can return the
+ * requested model directly or refresh reusable metadata before the sync retry.
  */
 export type ProviderPrepareDynamicModelContext = ProviderResolveDynamicModelContext;
 

From a17774e9b2d310606565091b287336298f823a25 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 11:41:48 -0700
Subject: [PATCH 063/124] perf(qa): reuse complete coverage inventory in report
 tests (#127376)

---
 extensions/qa-lab/src/coverage-report.test.ts | 25 +++++++++++--------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/extensions/qa-lab/src/coverage-report.test.ts b/extensions/qa-lab/src/coverage-report.test.ts
index 6665a76d3cc8..dda23a88d0c7 100644
--- a/extensions/qa-lab/src/coverage-report.test.ts
+++ b/extensions/qa-lab/src/coverage-report.test.ts
@@ -156,9 +156,13 @@ function scenarioWithCoverage(params: {
 }
 
 describe("qa coverage report", () => {
+  let catalogInventory: ReturnType<typeof buildQaCoverageInventory> | undefined;
+  const readCatalogInventory = () =>
+    (catalogInventory ??= buildQaCoverageInventory(readQaScenarioPack().scenarios));
+
   it("groups scenario coverage metadata by theme and surface", () => {
     const scenarios = readQaScenarioPack().scenarios;
-    const inventory = buildQaCoverageInventory(scenarios);
+    const inventory = readCatalogInventory();
 
     expect(inventory.scenarioCount).toBeGreaterThan(0);
     expect(inventory.coverageIdCount).toBeGreaterThan(0);
@@ -312,7 +316,7 @@ describe("qa coverage report", () => {
       { assert: { expr: expect.stringContaining("config.blockedMarker") } },
     ]);
 
-    const inventory = buildQaCoverageInventory(scenarios);
+    const inventory = readCatalogInventory();
     const coverage = expectDefined(
       inventory.coverageIds.find((candidate) => candidate.id === coverageId),
       "session turn ordering coverage inventory",
@@ -368,9 +372,7 @@ describe("qa coverage report", () => {
   });
 
   it("renders a compact markdown inventory", () => {
-    const report = renderQaCoverageMarkdownReport(
-      buildQaCoverageInventory(readQaScenarioPack().scenarios),
-    );
+    const report = renderQaCoverageMarkdownReport(readCatalogInventory());
 
     expect(report).toContain("# QA Coverage Inventory");
     expect(report).toContain("- Missing coverage metadata: 0");
@@ -454,13 +456,16 @@ describe("qa coverage report", () => {
 
   it("finds every cataloged native scenario by its authoritative execution path", () => {
     const scenarios = readQaScenarioPack().scenarios;
+    const matchesByExecutionPath = new Map<string, string[]>();
     for (const scenario of scenarios) {
-      if (scenario.execution.kind !== "flow") {
-        expect(
-          findQaScenarioMatches(scenarios, scenario.execution.path).map(({ id }) => id),
-          scenario.id,
-        ).toContain(scenario.id);
+      if (scenario.execution.kind === "flow") {
+        continue;
       }
+      const matchedIds =
+        matchesByExecutionPath.get(scenario.execution.path) ??
+        findQaScenarioMatches(scenarios, scenario.execution.path).map(({ id }) => id);
+      matchesByExecutionPath.set(scenario.execution.path, matchedIds);
+      expect(matchedIds, scenario.id).toContain(scenario.id);
     }
   });
 

From d06c0b83e3cb3527ff0d65456374f68b78ff621d Mon Sep 17 00:00:00 2001
From: Hannes Rudolph <hrudolph@gmail.com>
Date: Fri, 21 Aug 2026 12:47:06 -0600
Subject: [PATCH 064/124] fix(doctor): bound recovered session migrations
 (#126265)

* fix(doctor): bound recovered session migrations

* refactor(doctor): trim bounded migration flow

* test(doctor): strengthen migration heap regression

* test(doctor): cover media migration page boundary

---------

Co-authored-by: Josh Lehman <550978+jalehman@users.noreply.github.com>
---
 ...ons.media-persistence.large-corpus.test.ts | 146 +++++++
 .../state-migrations.media-persistence.ts     | 400 +++++++++---------
 2 files changed, 346 insertions(+), 200 deletions(-)
 create mode 100644 src/infra/state-migrations.media-persistence.large-corpus.test.ts

diff --git a/src/infra/state-migrations.media-persistence.large-corpus.test.ts b/src/infra/state-migrations.media-persistence.large-corpus.test.ts
new file mode 100644
index 000000000000..7a6c5abaf4fb
--- /dev/null
+++ b/src/infra/state-migrations.media-persistence.large-corpus.test.ts
@@ -0,0 +1,146 @@
+import { spawnSync } from "node:child_process";
+import { afterEach, describe, expect, it } from "vitest";
+import { useAutoCleanupTempDirTracker } from "../../test/helpers/temp-dir.js";
+import {
+  closeOpenClawAgentDatabases,
+  openOpenClawAgentDatabase,
+} from "../state/openclaw-agent-db.js";
+import { closeOpenClawStateDatabase } from "../state/openclaw-state-db.js";
+
+const SESSION_COUNT = 2_640;
+const ACTIVE_SESSIONS = 40;
+const EVENTS_PER_SESSION = 128;
+const PAYLOAD = "x".repeat(48 * 1024);
+const tempDir = useAutoCleanupTempDirTracker(afterEach);
+const CHILD_SCRIPT = String.raw`
+  import { createHash } from "node:crypto";
+  import { DatabaseSync } from "node:sqlite";
+  import { resolveOpenClawAgentSqlitePath } from "./src/state/openclaw-agent-db.ts";
+  import { migrateLegacyMediaPersistence } from "./src/infra/state-migrations.media-persistence.ts";
+  const path = resolveOpenClawAgentSqlitePath({ agentId: "main", env: process.env });
+  let db = new DatabaseSync(path, { readOnly: true });
+  const read = (session, seq) => db.prepare(
+    "SELECT event_json FROM transcript_events WHERE session_id=? AND seq=?",
+  ).get(session, seq).event_json;
+  const readTrajectory = (seq) => db.prepare(
+    "SELECT event_json FROM trajectory_runtime_events WHERE session_id=? AND seq=?",
+  ).get("large-corpus-0", seq).event_json;
+  const hash = (value) => createHash("sha256").update(value).digest("hex");
+  const before = [hash(read("large-corpus-20", 64)), hash(read("large-corpus-39", 127))];
+  db.close();
+  const migration = migrateLegacyMediaPersistence({
+    configuredAgentDatabaseTargets: [{ agentId: "main", path }], env: process.env,
+  });
+  db = new DatabaseSync(path, { readOnly: true });
+  const count = (table) => db.prepare("SELECT COUNT(*) count FROM " + table).get().count;
+  const first = JSON.parse(read("large-corpus-0", 0));
+  const boundary = JSON.parse(read("large-corpus-0", 64));
+  const trajectoryBoundary = JSON.parse(readTrajectory(64));
+  process.stdout.write(JSON.stringify({
+    warnings: migration.warnings,
+    changeCount: migration.changes.length,
+    sessions: count("session_nodes"), windows: count("session_windows"),
+    events: count("transcript_events"),
+    trajectoryEvents: count("trajectory_runtime_events"),
+    firstIdentity: [first.type, first.id, first.parentId],
+    firstMediaPath: first.message.__openclaw?.media?.[0]?.path,
+    firstHasLegacyCarrier: Object.hasOwn(first.message, "MediaPath"),
+    boundaryMediaPath: boundary.message.__openclaw?.media?.[0]?.path,
+    boundaryHasLegacyCarrier: Object.hasOwn(boundary.message, "MediaPath"),
+    trajectoryBoundaryMediaPath:
+      trajectoryBoundary.data.messagesSnapshot[0].__openclaw?.media?.[0]?.path,
+    trajectoryBoundaryHasLegacyCarrier: Object.hasOwn(
+      trajectoryBoundary.data.messagesSnapshot[0],
+      "MediaPath",
+    ),
+    middlePreserved: hash(read("large-corpus-20", 64)) === before[0],
+    lastPreserved: hash(read("large-corpus-39", 127)) === before[1],
+  }) + "\n");
+  db.close();
+`;
+
+function createCorpus(stateDir: string): void {
+  const database = openOpenClawAgentDatabase({
+    agentId: "main",
+    env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+  });
+  database.db.exec("BEGIN");
+  database.db
+    .prepare(`WITH RECURSIVE n(i) AS (
+    VALUES(0) UNION ALL SELECT i+1 FROM n WHERE i+1 < ?
+  ) INSERT INTO session_nodes(session_key,current_session_id,entry_json,entry_valid,updated_at)
+    SELECT 'agent:main:large-corpus-'||i, 'large-corpus-'||i,
+      json_object('sessionId','large-corpus-'||i,'updatedAt',i+1), 1, i+1 FROM n`)
+    .run(SESSION_COUNT);
+  database.db
+    .prepare(`WITH RECURSIVE n(i) AS (
+    VALUES(0) UNION ALL SELECT i+1 FROM n WHERE i+1 < ?
+  ) INSERT INTO session_windows(session_id,session_key,created_at,updated_at)
+    SELECT 'large-corpus-'||i, 'agent:main:large-corpus-'||i, i+1, i+1 FROM n`)
+    .run(SESSION_COUNT);
+  database.db
+    .prepare(`WITH RECURSIVE s(i) AS (
+    VALUES(0) UNION ALL SELECT i+1 FROM s WHERE i+1 < ?
+  ), e(seq) AS (VALUES(0) UNION ALL SELECT seq+1 FROM e WHERE seq+1 < ?)
+  INSERT INTO transcript_events(session_id,seq,event_json,created_at)
+    SELECT 'large-corpus-'||i, seq,
+      json_object('type','message','id','event-'||i||'-'||seq,'parentId',NULL,'message',
+        CASE WHEN i=0 AND seq=0
+          THEN json_object('role','user','content',?,'MediaPath','/media/legacy.png')
+          WHEN i=0 AND seq=64
+          THEN json_object('role','user','content',?,'MediaPath','/media/boundary.png')
+          ELSE json_object('role','user','content',?) END), seq+1 FROM s CROSS JOIN e`)
+    .run(ACTIVE_SESSIONS, EVENTS_PER_SESSION, PAYLOAD, PAYLOAD, PAYLOAD);
+  database.db
+    .prepare(`WITH RECURSIVE e(seq) AS (
+    VALUES(0) UNION ALL SELECT seq+1 FROM e WHERE seq+1 < ?
+  ) INSERT INTO trajectory_runtime_events(session_id,seq,run_id,event_json,created_at)
+    SELECT 'large-corpus-0', seq, 'run-large-corpus',
+      json_object('type','model.completed','data',json_object('messagesSnapshot',json_array(
+        CASE WHEN seq=64
+          THEN json_object('role','user','content','trajectory','MediaPath','/media/trajectory-boundary.png')
+          ELSE json_object('role','user','content','trajectory') END))), seq+1 FROM e`)
+    .run(EVENTS_PER_SESSION);
+  database.db.exec("COMMIT; UPDATE session_nodes SET entry_valid=1");
+  closeOpenClawAgentDatabases();
+}
+
+describe("legacy media persistence large corpus", () => {
+  it("rewrites bounded batches under a 256 MiB old-space cap", () => {
+    const stateDir = tempDir.make("openclaw-media-corpus-");
+    try {
+      createCorpus(stateDir);
+      const result = spawnSync(
+        process.execPath,
+        ["--max-old-space-size=256", "--import", "tsx", "--input-type=module", "-e", CHILD_SCRIPT],
+        {
+          cwd: process.cwd(),
+          encoding: "utf8",
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+          timeout: 120_000,
+        },
+      );
+      expect(result.status, result.stderr).toBe(0);
+      expect(JSON.parse(result.stdout)).toMatchObject({
+        warnings: [],
+        changeCount: 1,
+        sessions: SESSION_COUNT,
+        windows: SESSION_COUNT,
+        events: ACTIVE_SESSIONS * EVENTS_PER_SESSION,
+        trajectoryEvents: EVENTS_PER_SESSION,
+        firstIdentity: ["message", "event-0-0", null],
+        firstMediaPath: "/media/legacy.png",
+        firstHasLegacyCarrier: false,
+        boundaryMediaPath: "/media/boundary.png",
+        boundaryHasLegacyCarrier: false,
+        trajectoryBoundaryMediaPath: "/media/trajectory-boundary.png",
+        trajectoryBoundaryHasLegacyCarrier: false,
+        middlePreserved: true,
+        lastPreserved: true,
+      });
+    } finally {
+      closeOpenClawAgentDatabases();
+      closeOpenClawStateDatabase();
+    }
+  }, 130_000);
+});
diff --git a/src/infra/state-migrations.media-persistence.ts b/src/infra/state-migrations.media-persistence.ts
index a5f6a99bff9a..7879e9ee10b5 100644
--- a/src/infra/state-migrations.media-persistence.ts
+++ b/src/infra/state-migrations.media-persistence.ts
@@ -41,42 +41,23 @@ import {
 import { openNodeSqliteDatabase } from "./node-sqlite.js";
 import { replaceFileAtomicSync } from "./replace-file.js";
 import { repairCanonicalSqliteIndexes } from "./sqlite-index-schema.js";
-import { runSqliteImmediateTransactionSync } from "./sqlite-transaction.js";
+import {
+  runSqliteDeferredTransactionSync,
+  runSqliteImmediateTransactionSync,
+} from "./sqlite-transaction.js";
 import { readSqliteUserVersion } from "./sqlite-user-version.js";
 import { resolveAgentDatabaseMigrationTargets } from "./state-migrations.media-persistence-targets.js";
 import type { MigrationMessages } from "./state-migrations.types.js";
 
 const PREVIOUS_MEDIA_SCHEMA_VERSION = OPENCLAW_AGENT_SCHEMA_VERSION - 1;
 const ARCHIVE_TEMP_MARKER = ".media-retirement";
+const MEDIA_MIGRATION_ROW_BATCH_SIZE = 64;
 
 type MediaMigrationDatabase = Pick<
   OpenClawAgentKyselyDatabase,
   "schema_meta" | "session_windows" | "trajectory_runtime_events" | "transcript_events"
 >;
 
-type TranscriptRowSnapshot = {
-  createdAt: number;
-  event: TranscriptEvent;
-  eventJson: string;
-  seq: number;
-  sessionId: string;
-};
-
-type SessionRewritePlan = {
-  changed: boolean;
-  events: TranscriptEvent[];
-  rows: TranscriptRowSnapshot[];
-  sessionId: string;
-  sessionKey: string;
-};
-
-type TrajectoryRowRewritePlan = {
-  eventJson: string;
-  rewrittenEventJson: string;
-  seq: number;
-  sessionId: string;
-};
-
 type ArchiveSourceSnapshot = {
   dev: number;
   ino: number;
@@ -134,108 +115,95 @@ function assertEventIdentitiesUnchanged(
   }
 }
 
-function planTranscriptRows(database: DatabaseSync, pathname: string): SessionRewritePlan[] {
+function forEachMediaEventBatch(params: {
+  database: DatabaseSync;
+  table: "trajectory_runtime_events" | "transcript_events";
+  visit: (sessionId: string, rows: Array<{ event_json: string; seq: number }>) => void;
+}): void {
+  const db = getNodeSqliteKysely<MediaMigrationDatabase>(params.database);
+  const sessionIds = executeSqliteQuerySync(
+    params.database,
+    db.selectFrom(params.table).select("session_id").distinct().orderBy("session_id", "asc"),
+  ).rows.map((row) => row.session_id);
+  for (const sessionId of sessionIds) {
+    let afterSeq: number | undefined;
+    while (true) {
+      let query = db
+        .selectFrom(params.table)
+        .select(["seq", "event_json"])
+        .where("session_id", "=", sessionId)
+        .orderBy("seq", "asc")
+        .limit(MEDIA_MIGRATION_ROW_BATCH_SIZE);
+      if (afterSeq !== undefined) {
+        query = query.where("seq", ">", afterSeq);
+      }
+      const rows = executeSqliteQuerySync(params.database, query).rows;
+      if (rows.length === 0) {
+        break;
+      }
+      params.visit(sessionId, rows);
+      afterSeq = rows.at(-1)?.seq;
+    }
+  }
+}
+
+function scanTranscriptRows(params: {
+  database: DatabaseSync;
+  pathname: string;
+  writer?: OpenClawAgentDatabase;
+}): number {
+  const { database, pathname, writer } = params;
   const db = getNodeSqliteKysely<MediaMigrationDatabase>(database);
   const sessionRows = executeSqliteQuerySync(
     database,
     db.selectFrom("session_windows").select(["session_id", "session_key"]),
   ).rows;
   const sessionKeys = new Map(sessionRows.map((row) => [row.session_id, row.session_key]));
-  const rows = executeSqliteQuerySync(
+  const changedSessionIds = new Set<string>();
+  forEachMediaEventBatch({
     database,
-    db
-      .selectFrom("transcript_events")
-      .select(["session_id", "seq", "event_json", "created_at"])
-      .orderBy("session_id", "asc")
-      .orderBy("seq", "asc"),
-  ).rows;
-  const bySession = new Map<string, TranscriptRowSnapshot[]>();
-  for (const row of rows) {
-    const snapshots = bySession.get(row.session_id) ?? [];
-    snapshots.push({
-      createdAt: row.created_at,
-      event: parseTranscriptEvent(row.event_json, `${pathname}:${row.session_id}:${row.seq}`),
-      eventJson: row.event_json,
-      seq: row.seq,
-      sessionId: row.session_id,
-    });
-    bySession.set(row.session_id, snapshots);
-  }
-  return [...bySession].map(([sessionId, snapshots]) => {
-    const sessionKey = sessionKeys.get(sessionId);
-    if (!sessionKey) {
-      throw new Error(`${pathname}:${sessionId} has transcript rows without a session window`);
-    }
-    let changed = false;
-    const events = snapshots.map((row) => {
-      const transformed = transformTranscriptEvent(row.event);
-      changed ||= transformed.changed;
-      return transformed.event;
-    });
-    assertEventIdentitiesUnchanged(
-      snapshots.map((row) => row.event),
-      events,
-      `${pathname}:${sessionId}`,
-    );
-    return { changed, events, rows: snapshots, sessionId, sessionKey };
+    table: "transcript_events",
+    visit: (sessionId, rows) => {
+      const sessionKey = sessionKeys.get(sessionId);
+      if (!sessionKey) {
+        throw new Error(`${pathname}:${sessionId} has transcript rows without a session window`);
+      }
+      const rewrites = rows.flatMap((row) => {
+        const owner = `${pathname}:${sessionId}:${row.seq}`;
+        const event = parseTranscriptEvent(row.event_json, owner);
+        const transformed = transformTranscriptEvent(event);
+        if (!transformed.changed) {
+          return [];
+        }
+        if (eventIdentity(event) !== eventIdentity(transformed.event)) {
+          throw new Error(`${owner} event identity changed during media migration`);
+        }
+        changedSessionIds.add(sessionId);
+        return [{ event: transformed.event, expectedEventJson: row.event_json, seq: row.seq }];
+      });
+      if (writer && rewrites.length > 0) {
+        rewriteSqliteTranscriptEventRowsInTransaction(
+          writer,
+          { agentId: writer.agentId, path: pathname, sessionId, sessionKey },
+          rewrites,
+        );
+      }
+    },
   });
+  return changedSessionIds.size;
 }
 
-function assertTranscriptSourceUnchanged(
-  database: DatabaseSync,
-  pathname: string,
-  planned: readonly SessionRewritePlan[],
-): void {
-  const db = getNodeSqliteKysely<MediaMigrationDatabase>(database);
-  const current = executeSqliteQuerySync(
-    database,
-    db
-      .selectFrom("transcript_events")
-      .select(["session_id", "seq", "event_json", "created_at"])
-      .orderBy("session_id", "asc")
-      .orderBy("seq", "asc"),
-  ).rows;
-  const expected = planned.flatMap((session) => session.rows);
-  if (current.length !== expected.length) {
-    throw new Error(`${pathname} transcript source changed before migration commit`);
-  }
-  for (let index = 0; index < expected.length; index += 1) {
-    const left = current[index];
-    const right = expected[index];
-    if (
-      !left ||
-      !right ||
-      left.session_id !== right.sessionId ||
-      left.seq !== right.seq ||
-      left.event_json !== right.eventJson ||
-      left.created_at !== right.createdAt
-    ) {
-      throw new Error(`${pathname} transcript source changed before migration commit`);
-    }
-  }
-}
-
-function planTrajectoryRowRewrite(params: {
-  eventJson: string;
-  owner: string;
-  seq: number;
-  sessionId: string;
-}): TrajectoryRowRewritePlan {
+function rewriteTrajectoryEventJson(eventJson: string, owner: string): string {
   let event: unknown;
   try {
-    event = JSON.parse(params.eventJson) as unknown;
+    event = JSON.parse(eventJson) as unknown;
   } catch (error) {
-    throw new Error(`${params.owner} contains invalid trajectory JSON: ${String(error)}`, {
+    throw new Error(`${owner} contains invalid trajectory JSON: ${String(error)}`, {
       cause: error,
     });
   }
   if (!isRecord(event) || !isRecord(event.data) || !Array.isArray(event.data.messagesSnapshot)) {
-    return {
-      eventJson: params.eventJson,
-      rewrittenEventJson: params.eventJson,
-      seq: params.seq,
-      sessionId: params.sessionId,
-    };
+    return eventJson;
   }
   let changed = false;
   const messagesSnapshot = event.data.messagesSnapshot.map((message) => {
@@ -246,49 +214,101 @@ function planTrajectoryRowRewrite(params: {
     changed ||= canonical.changed;
     return canonical.message;
   });
+  return changed
+    ? JSON.stringify({ ...event, data: { ...event.data, messagesSnapshot } })
+    : eventJson;
+}
+
+function scanTrajectoryRows(params: {
+  database: DatabaseSync;
+  pathname: string;
+  rewrite: boolean;
+}): number {
+  const { database, pathname, rewrite } = params;
+  const db = getNodeSqliteKysely<MediaMigrationDatabase>(database);
+  let changedRows = 0;
+  forEachMediaEventBatch({
+    database,
+    table: "trajectory_runtime_events",
+    visit: (sessionId, rows) => {
+      for (const row of rows) {
+        const rewrittenEventJson = rewriteTrajectoryEventJson(
+          row.event_json,
+          `${pathname}:${sessionId}:${row.seq}`,
+        );
+        if (rewrittenEventJson === row.event_json) {
+          continue;
+        }
+        changedRows += 1;
+        if (rewrite) {
+          executeSqliteQuerySync(
+            database,
+            db
+              .updateTable("trajectory_runtime_events")
+              .set({ event_json: rewrittenEventJson })
+              .where("session_id", "=", sessionId)
+              .where("seq", "=", row.seq),
+          );
+        }
+      }
+    },
+  });
+  return changedRows;
+}
+
+type MediaSourceVersion = {
+  dataVersion: number;
+  trajectoryBytes: number;
+  trajectoryRows: number;
+  transcriptBytes: number;
+  transcriptCreatedAt: number;
+  transcriptRows: number;
+};
+
+function readMediaSourceVersion(database: DatabaseSync): MediaSourceVersion {
+  const dataVersionRow = database.prepare("PRAGMA data_version").get();
+  const counts = database
+    .prepare(
+      `SELECT
+        (SELECT COUNT(*) FROM transcript_events) AS transcript_rows,
+        (SELECT COALESCE(SUM(LENGTH(event_json)), 0) FROM transcript_events) AS transcript_bytes,
+        (SELECT COALESCE(SUM(created_at), 0) FROM transcript_events) AS transcript_created_at,
+        (SELECT COUNT(*) FROM trajectory_runtime_events) AS trajectory_rows,
+        (SELECT COALESCE(SUM(LENGTH(event_json)), 0) FROM trajectory_runtime_events) AS trajectory_bytes`,
+    )
+    .get();
+  const number = (value: unknown): number =>
+    typeof value === "bigint" ? Number(value) : typeof value === "number" ? value : 0;
+  const count = (key: string): number => number(isRecord(counts) ? counts[key] : undefined);
   return {
-    eventJson: params.eventJson,
-    rewrittenEventJson: changed
-      ? JSON.stringify({
-          ...event,
-          data: { ...event.data, messagesSnapshot },
-        })
-      : params.eventJson,
-    seq: params.seq,
-    sessionId: params.sessionId,
+    dataVersion: number(isRecord(dataVersionRow) ? dataVersionRow.data_version : undefined),
+    trajectoryBytes: count("trajectory_bytes"),
+    trajectoryRows: count("trajectory_rows"),
+    transcriptBytes: count("transcript_bytes"),
+    transcriptCreatedAt: count("transcript_created_at"),
+    transcriptRows: count("transcript_rows"),
   };
 }
 
-function assertTrajectorySourceUnchanged(
-  database: DatabaseSync,
+function mediaSourceDriftMessage(
   pathname: string,
-  planned: readonly TrajectoryRowRewritePlan[],
-): void {
-  const db = getNodeSqliteKysely<MediaMigrationDatabase>(database);
-  const current = executeSqliteQuerySync(
-    database,
-    db
-      .selectFrom("trajectory_runtime_events")
-      .select(["session_id", "seq", "event_json"])
-      .orderBy("session_id", "asc")
-      .orderBy("seq", "asc"),
-  ).rows;
-  if (current.length !== planned.length) {
-    throw new Error(`${pathname} trajectory source changed before migration commit`);
+  expected: MediaSourceVersion,
+  current: MediaSourceVersion,
+): string {
+  if (
+    expected.transcriptRows !== current.transcriptRows ||
+    expected.transcriptBytes !== current.transcriptBytes ||
+    expected.transcriptCreatedAt !== current.transcriptCreatedAt
+  ) {
+    return `${pathname} transcript source changed before migration commit`;
   }
-  for (let index = 0; index < planned.length; index += 1) {
-    const left = current[index];
-    const right = planned[index];
-    if (
-      !left ||
-      !right ||
-      left.session_id !== right.sessionId ||
-      left.seq !== right.seq ||
-      left.event_json !== right.eventJson
-    ) {
-      throw new Error(`${pathname} trajectory source changed before migration commit`);
-    }
+  if (
+    expected.trajectoryRows !== current.trajectoryRows ||
+    expected.trajectoryBytes !== current.trajectoryBytes
+  ) {
+    return `${pathname} trajectory source changed before migration commit`;
   }
+  return `${pathname} source changed before migration transaction`;
 }
 
 function createMigrationDatabaseHandle(
@@ -357,69 +377,49 @@ function migrateAgentDatabase(params: {
       });
     }
     assertOpenClawAgentSchemaContains(database, params.pathname, OPENCLAW_AGENT_SCHEMA_SQL);
-    const planned = planTranscriptRows(database, params.pathname);
-    const db = getNodeSqliteKysely<MediaMigrationDatabase>(database);
-    const plannedTrajectoryRows = executeSqliteQuerySync(
-      database,
-      db
-        .selectFrom("trajectory_runtime_events")
-        .select(["session_id", "seq", "event_json"])
-        .orderBy("session_id", "asc")
-        .orderBy("seq", "asc"),
-    ).rows.map((row) =>
-      planTrajectoryRowRewrite({
-        eventJson: row.event_json,
-        owner: `${params.pathname}:${row.session_id}:${row.seq}`,
-        seq: row.seq,
-        sessionId: row.session_id,
-      }),
-    );
-    const changedTrajectoryRows = plannedTrajectoryRows.filter(
-      (row) => row.rewrittenEventJson !== row.eventJson,
-    );
-    const changedSessions = planned.filter((session) => session.changed);
     const versionAdvanced = userVersion === PREVIOUS_MEDIA_SCHEMA_VERSION;
-    if (!versionAdvanced && changedSessions.length === 0 && changedTrajectoryRows.length === 0) {
-      return { rewrittenSessions: 0, rewrittenTrajectoryRows: 0, versionAdvanced: false };
+    if (!versionAdvanced) {
+      const detected = runSqliteDeferredTransactionSync(
+        database,
+        () => ({
+          rewrittenSessions: scanTranscriptRows({ database, pathname: params.pathname }),
+          rewrittenTrajectoryRows: scanTrajectoryRows({
+            database,
+            pathname: params.pathname,
+            rewrite: false,
+          }),
+        }),
+        { databaseLabel: params.pathname, operationLabel: "media-persistence-detection" },
+      );
+      if (detected.rewrittenSessions === 0 && detected.rewrittenTrajectoryRows === 0) {
+        return { ...detected, versionAdvanced: false };
+      }
     }
 
+    const sourceVersion = readMediaSourceVersion(database);
     params.beforeTransaction?.();
     const owner = createMigrationDatabaseHandle(database, params.agentId, params.pathname);
-    runSqliteImmediateTransactionSync(
+    const rewritten = runSqliteImmediateTransactionSync(
       database,
       () => {
-        assertTranscriptSourceUnchanged(database, params.pathname, planned);
-        assertTrajectorySourceUnchanged(database, params.pathname, plannedTrajectoryRows);
-        for (const session of changedSessions) {
-          const rows = session.events.flatMap((event, index) => {
-            const source = session.rows[index];
-            if (!source || JSON.stringify(event) === source.eventJson) {
-              return [];
-            }
-            return [{ event, expectedEventJson: source.eventJson, seq: source.seq }];
-          });
-          rewriteSqliteTranscriptEventRowsInTransaction(
-            owner,
-            {
-              agentId: params.agentId,
-              path: params.pathname,
-              sessionId: session.sessionId,
-              sessionKey: session.sessionKey,
-            },
-            rows,
-          );
-        }
-        for (const row of changedTrajectoryRows) {
-          executeSqliteQuerySync(
-            database,
-            db
-              .updateTable("trajectory_runtime_events")
-              .set({ event_json: row.rewrittenEventJson })
-              .where("session_id", "=", row.sessionId)
-              .where("seq", "=", row.seq),
+        const currentSourceVersion = readMediaSourceVersion(database);
+        if (currentSourceVersion.dataVersion !== sourceVersion.dataVersion) {
+          throw new Error(
+            mediaSourceDriftMessage(params.pathname, sourceVersion, currentSourceVersion),
           );
         }
+        const rewrittenSessions = scanTranscriptRows({
+          database,
+          pathname: params.pathname,
+          writer: owner,
+        });
+        const rewrittenTrajectoryRows = scanTrajectoryRows({
+          database,
+          pathname: params.pathname,
+          rewrite: true,
+        });
         if (versionAdvanced) {
+          const db = getNodeSqliteKysely<MediaMigrationDatabase>(database);
           database.exec(`PRAGMA user_version = ${OPENCLAW_AGENT_SCHEMA_VERSION};`);
           executeSqliteQuerySync(
             database,
@@ -433,6 +433,7 @@ function migrateAgentDatabase(params: {
               .where("meta_key", "=", "primary"),
           );
         }
+        return { rewrittenSessions, rewrittenTrajectoryRows };
       },
       {
         busyTimeoutMs: OPENCLAW_SQLITE_BUSY_TIMEOUT_MS,
@@ -441,8 +442,7 @@ function migrateAgentDatabase(params: {
       },
     );
     return {
-      rewrittenSessions: changedSessions.length,
-      rewrittenTrajectoryRows: changedTrajectoryRows.length,
+      ...rewritten,
       versionAdvanced,
     };
   } finally {

From 9a0e11df066dea98b20e96a3f43a8d3342c89ca7 Mon Sep 17 00:00:00 2001
From: SunnyShu <shu.zongyu@xydigit.com>
Date: Sat, 22 Aug 2026 02:48:36 +0800
Subject: [PATCH 065/124] fix(ui): reach identity-menu footer controls with
 keyboard (#122066)

* fix(ui): restore identity menu footer keyboard navigation

Co-authored-by: SunnyShu0925 <shu.zongyu@xydigit.com>

* test(ui): synchronize identity menu hide lifecycle

* test(ui): keep identity keyboard proof in one menu lifecycle

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 ui/src/components/app-sidebar-agent-menu.ts   | 62 ++++++++++-----
 ...-sidebar-identity-keyboard.browser.test.ts | 78 +++++++++++++++++++
 .../app-sidebar-cases/identity-menu.ts        | 61 +++++++++++++++
 3 files changed, 182 insertions(+), 19 deletions(-)
 create mode 100644 ui/src/components/app-sidebar-identity-keyboard.browser.test.ts

diff --git a/ui/src/components/app-sidebar-agent-menu.ts b/ui/src/components/app-sidebar-agent-menu.ts
index fdb2a14c2115..a0f6fc60923d 100644
--- a/ui/src/components/app-sidebar-agent-menu.ts
+++ b/ui/src/components/app-sidebar-agent-menu.ts
@@ -61,6 +61,43 @@ function closeMenuAfterOwnDropdownHide(event: Event, onClose: (restoreFocus?: bo
   onClose(consumeDropdownKeyboardDismissal(event));
 }
 
+function moveSidebarMenuFocus(event: KeyboardEvent): boolean {
+  if (event.key !== "ArrowDown" && event.key !== "ArrowUp") {
+    return false;
+  }
+  const dropdown = (event.currentTarget as HTMLElement).closest("wa-dropdown");
+  const items = [
+    ...(dropdown?.querySelectorAll<HTMLElement & { active: boolean }>(
+      ":scope > wa-dropdown-item:not([disabled])",
+    ) ?? []),
+  ];
+  const footer = dropdown?.querySelector<HTMLElement>(".sidebar-identity-menu__footer");
+  const controls = [
+    ...items,
+    ...(footer?.querySelectorAll<HTMLElement>("a[href], button:not([disabled])") ?? []),
+  ];
+  const current = event.target instanceof HTMLElement ? event.target : null;
+  const index = current ? controls.indexOf(current) : -1;
+  if (footer && index < 0) {
+    return false;
+  }
+  const direction = event.key === "ArrowDown" ? 1 : -1;
+  const target =
+    index < 0
+      ? items.at(direction === 1 ? 0 : -1)
+      : controls[(index + direction + controls.length) % controls.length];
+  if (!target || (footer && !footer.contains(current) && !footer.contains(target))) {
+    return false;
+  }
+  event.preventDefault();
+  event.stopPropagation();
+  // Native footer actions are outside Web Awesome's roving item list; reset
+  // its active row on both crossings so reverse navigation cannot skip one.
+  items.forEach((item) => (item.active = item === target));
+  target.focus({ preventScroll: true });
+  return true;
+}
+
 type AgentMenuAgent = {
   id: string;
   name?: string;
@@ -321,23 +358,7 @@ export function renderSidebarAgentMenu(params: SidebarAgentMenuParams) {
                         @input=${(event: Event) =>
                           params.onFilterChange((event.target as HTMLInputElement).value)}
                         @keydown=${(event: KeyboardEvent) => {
-                          if (event.key === "ArrowDown" || event.key === "ArrowUp") {
-                            event.preventDefault();
-                            event.stopPropagation();
-                            const dropdown = (event.currentTarget as HTMLElement).closest(
-                              "wa-dropdown",
-                            );
-                            const items = Array.from(dropdown?.children ?? []).filter(
-                              (child): child is HTMLElement & { active: boolean } =>
-                                child instanceof HTMLElement &&
-                                child.localName === "wa-dropdown-item" &&
-                                !child.hasAttribute("disabled"),
-                            );
-                            const target = event.key === "ArrowDown" ? items.at(0) : items.at(-1);
-                            if (target) {
-                              items.forEach((item) => (item.active = item === target));
-                              target.focus({ preventScroll: true });
-                            }
+                          if (moveSidebarMenuFocus(event)) {
                             return;
                           }
                           // Keep editing keys out of Web Awesome's document-level
@@ -438,8 +459,11 @@ export function renderSidebarIdentityMenu(params: SidebarIdentityMenuParams) {
               break;
           }
         }}
-        @keydown=${(event: KeyboardEvent) =>
-          trackDropdownKeyboardDismissal(event, params.onTabAway)}
+        @keydown=${(event: KeyboardEvent) => {
+          if (!moveSidebarMenuFocus(event)) {
+            trackDropdownKeyboardDismissal(event, params.onTabAway);
+          }
+        }}
         @wa-after-hide=${(event: Event) => closeMenuAfterOwnDropdownHide(event, params.onClose)}
       >
         <button
diff --git a/ui/src/components/app-sidebar-identity-keyboard.browser.test.ts b/ui/src/components/app-sidebar-identity-keyboard.browser.test.ts
new file mode 100644
index 000000000000..2a81b0b7f503
--- /dev/null
+++ b/ui/src/components/app-sidebar-identity-keyboard.browser.test.ts
@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, it } from "vitest";
+import type { GatewayBrowserClient } from "../api/gateway.ts";
+import "../test-helpers/load-styles.ts";
+
+afterEach(() => document.body.replaceChildren());
+
+describe.runIf("__vitest_browser__" in globalThis)("identity menu keyboard navigation", () => {
+  it("traverses the actual item order and both footer controls in each direction", async () => {
+    await import("./app-sidebar.ts");
+    const { createGatewayHarness, createSessions, mountSidebar } =
+      await import("../test-helpers/app-sidebar.ts");
+    const { userEvent } = await import("vitest/browser");
+    const { sidebar } = await mountSidebar(
+      createGatewayHarness({ instanceId: "self-instance" } as GatewayBrowserClient).gateway,
+      createSessions("main", ["agent:main:main"]),
+    );
+    sidebar.connected = true;
+    sidebar.canPairDevice = false;
+    await sidebar.updateComplete;
+
+    const identity = sidebar.querySelector<HTMLButtonElement>(".sidebar-identity-card");
+    expect(identity).not.toBeNull();
+    identity?.focus();
+    await userEvent.keyboard("{Enter}");
+
+    const menu = sidebar.querySelector<HTMLElement>(".sidebar-identity-menu");
+    const items = Array.from(menu?.children ?? []).filter(
+      (item): item is HTMLElement & { active: boolean } =>
+        item instanceof HTMLElement &&
+        item.localName === "wa-dropdown-item" &&
+        !item.hasAttribute("disabled"),
+    );
+    const theme = menu?.querySelector<HTMLButtonElement>(".theme-mode-toggle");
+    const build = document.createElement("a");
+    build.href = "#build";
+    build.textContent = "Build details";
+    menu?.querySelector(".sidebar-mode-switch")?.insertAdjacentElement("beforebegin", build);
+    await expect.poll(() => document.activeElement).toBe(items[0]);
+
+    for (const expected of items.slice(1)) {
+      await userEvent.keyboard("{ArrowDown}");
+      expect(document.activeElement).toBe(expected);
+    }
+    expect(items.at(-1)?.active).toBe(true);
+    await userEvent.keyboard("{ArrowRight}");
+    await expect.poll(() => document.activeElement?.getAttribute("slot")).toBe("submenu");
+    await userEvent.keyboard("{ArrowDown}");
+    expect(document.activeElement?.getAttribute("slot")).toBe("submenu");
+    await userEvent.keyboard("{ArrowLeft}");
+    await expect.poll(() => document.activeElement).toBe(items.at(-1));
+    await userEvent.keyboard("{ArrowDown}");
+    expect(document.activeElement).toBe(build);
+    await userEvent.keyboard("{ArrowDown}");
+    expect(document.activeElement).toBe(theme);
+    await userEvent.keyboard("{ArrowUp}");
+    expect(document.activeElement).toBe(build);
+    await userEvent.keyboard("{ArrowUp}");
+    expect(document.activeElement).toBe(items.at(-1));
+    expect(items.at(-1)?.active).toBe(true);
+
+    build.remove();
+    await userEvent.keyboard("{ArrowDown}");
+    expect(document.activeElement).toBe(theme);
+    const onThemeChange = new Promise<CustomEvent<{ mode: string }>>((resolve) => {
+      menu?.addEventListener(
+        "theme-change",
+        (event) => resolve(event as CustomEvent<{ mode: string }>),
+        {
+          once: true,
+        },
+      );
+    });
+    await userEvent.keyboard("{Enter}");
+    expect((await onThemeChange).detail.mode).toBe("light");
+    await userEvent.keyboard("{Tab}");
+    await expect.poll(() => (menu as HTMLElement & { open: boolean }).open).toBe(false);
+  });
+});
diff --git a/ui/src/test-helpers/app-sidebar-cases/identity-menu.ts b/ui/src/test-helpers/app-sidebar-cases/identity-menu.ts
index 3914e21d29d1..60a0f720fdca 100644
--- a/ui/src/test-helpers/app-sidebar-cases/identity-menu.ts
+++ b/ui/src/test-helpers/app-sidebar-cases/identity-menu.ts
@@ -99,4 +99,65 @@ describe("AppSidebar footer identity menu", () => {
     expect(onNavigate).toHaveBeenCalledWith("profile", { hash: "#settings-profile-identity" });
     expect(sidebar.querySelector(".sidebar-identity-menu")).toBeNull();
   });
+
+  it.each([false, true])(
+    "traverses footer controls without losing the active menu item (offline: %s)",
+    async (offline) => {
+      const { sidebar } = await mountSidebar(
+        createGatewayHarness({ instanceId: "self-instance" } as GatewayBrowserClient).gateway,
+        createSessions("main", ["agent:main:main"]),
+      );
+      sidebar.connected = true;
+      sidebar.canPairDevice = false;
+      sidebar.offline = offline;
+      await sidebar.updateComplete;
+
+      const identity = sidebar.querySelector<HTMLButtonElement>(".sidebar-identity-card");
+      identity?.click();
+      await sidebar.updateComplete;
+
+      const menu = sidebar.querySelector<HTMLElement>(".sidebar-identity-menu");
+      const items = Array.from(menu?.children ?? []).filter(
+        (item): item is HTMLElement & { active: boolean } =>
+          item instanceof HTMLElement &&
+          item.localName === "wa-dropdown-item" &&
+          !item.hasAttribute("disabled"),
+      );
+      const lastItem = items.at(-1);
+      const theme = menu?.querySelector<HTMLButtonElement>(".theme-mode-toggle");
+      const build = document.createElement("a");
+      build.href = "#build";
+      menu?.querySelector(".sidebar-mode-switch")?.insertAdjacentElement("beforebegin", build);
+
+      const arrow = (target: HTMLElement | undefined, key: "ArrowDown" | "ArrowUp") => {
+        target?.dispatchEvent(
+          new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true }),
+        );
+      };
+      items.forEach((item) => (item.active = item === lastItem));
+      lastItem?.focus();
+      arrow(lastItem, "ArrowDown");
+      expect(document.activeElement).toBe(build);
+      arrow(build, "ArrowDown");
+      expect(document.activeElement).toBe(theme);
+      arrow(theme ?? undefined, "ArrowUp");
+      expect(document.activeElement).toBe(build);
+      arrow(build, "ArrowUp");
+      expect(document.activeElement).toBe(lastItem);
+      expect(lastItem?.active).toBe(true);
+
+      build.remove();
+      arrow(lastItem, "ArrowDown");
+      expect(document.activeElement).toBe(theme);
+      arrow(theme ?? undefined, "ArrowUp");
+      expect(document.activeElement).toBe(lastItem);
+
+      items[0]?.focus();
+      items.forEach((item) => (item.active = item === items[0]));
+      arrow(items[0], "ArrowUp");
+      expect(document.activeElement).toBe(theme);
+      arrow(theme ?? undefined, "ArrowDown");
+      expect(document.activeElement).toBe(items[0]);
+    },
+  );
 });

From 35175c314b51a9afbc7e24cc47aab855432524a9 Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Fri, 21 Aug 2026 11:51:17 -0700
Subject: [PATCH 066/124] perf(agents): reuse active gateway plugin generation
 (#127278)

Reuse the active Gateway registry only for the exact current metadata generation and matching runtime authority. Seed selected-runtime loading from imported inbound plugin IDs so deferred records remain eligible for their scoped load, while the generation owner continues to supply built-artifact preference.

Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 ...prepared-model-runtime.inbound-registry.ts |  31 ++---
 ...pared-model-runtime.plugin-context.test.ts |   2 +-
 .../prepared-model-runtime.plugin-context.ts  |   5 +-
 ...pared-model-runtime.startup-static.test.ts |   5 +-
 src/agents/runtime-plugins.test.ts            | 109 ++++++++++--------
 5 files changed, 75 insertions(+), 77 deletions(-)

diff --git a/src/agents/prepared-model-runtime.inbound-registry.ts b/src/agents/prepared-model-runtime.inbound-registry.ts
index de27cd758de7..941f16679c77 100644
--- a/src/agents/prepared-model-runtime.inbound-registry.ts
+++ b/src/agents/prepared-model-runtime.inbound-registry.ts
@@ -56,23 +56,19 @@ export function createPreparedInboundRegistryLoader(): PreparedInboundRegistryLo
       return existing;
     }
     const activeRegistry = getActivePluginRegistry();
-    const activeWorkspaceDir = getActivePluginRegistryWorkspaceDir();
-    // Reuse is generation-bound: the requesting snapshot must BE the process-current
-    // published generation, or a leaked/older active registry could satisfy the
-    // manifest match (bundled records compare by id+origin only) and serve another
-    // generation's plugins. Identity, not equivalence, is the authority check here.
-    const currentGenerationSnapshot = getCurrentPluginMetadataSnapshot({
-      config: input.config,
-      workspaceDir: metadataSnapshot.workspaceDir,
-      allowWorkspaceScopedSnapshot: true,
-    });
+    // Identity is the generation authority. Manifest equivalence alone could let a
+    // stale active registry satisfy a newer bundled snapshot.
     const reusableGatewayRegistry =
       input.allowGatewaySubagentBinding === true &&
       input.env === undefined &&
       getActivePluginRuntimeSubagentMode() === "gateway-bindable" &&
       activeRegistry &&
-      currentGenerationSnapshot === metadataSnapshot &&
-      (activeWorkspaceDir === undefined || activeWorkspaceDir === metadataSnapshot.workspaceDir) &&
+      getActivePluginRegistryWorkspaceDir() === metadataSnapshot.workspaceDir &&
+      getCurrentPluginMetadataSnapshot({
+        config: input.config,
+        workspaceDir: metadataSnapshot.workspaceDir,
+        allowWorkspaceScopedSnapshot: true,
+      }) === metadataSnapshot &&
       registryMatchesManifestPluginIds(
         activeRegistry,
         metadataSnapshot.manifestRegistry.plugins,
@@ -113,11 +109,6 @@ export function prepareWorkspacePluginRegistries(
   const inboundPluginRegistry = input.readOnly
     ? undefined
     : loadInboundRegistry?.(input, metadataSnapshot);
-  // Extending the reused Gateway generation inherits its artifact preference: the
-  // Gateway loader realizes built artifacts, so the delta load must not re-import
-  // the same plugins through source transforms. Isolated loads keep source truth.
-  const extendsActiveGatewayGeneration =
-    inboundPluginRegistry !== undefined && inboundPluginRegistry === getActivePluginRegistry();
   const runtimePluginRegistry =
     input.runtimePluginSelections || !inboundPluginRegistry
       ? loadAgentRuntimePluginRegistryHandle({
@@ -131,11 +122,7 @@ export function prepareWorkspacePluginRegistries(
           ...(input.workspaceDir ? { workspaceDir: input.workspaceDir } : {}),
           ...(input.allowGatewaySubagentBinding ? { allowGatewaySubagentBinding: true } : {}),
           metadataSnapshot,
-          // Lifecycle-selected callers and delta loads extending the active Gateway
-          // generation both stay on built artifacts; isolated loads keep source truth.
-          ...(preferBuiltPluginArtifacts || extendsActiveGatewayGeneration
-            ? { preferBuiltPluginArtifacts: true }
-            : {}),
+          ...(preferBuiltPluginArtifacts ? { preferBuiltPluginArtifacts: true } : {}),
           selections: input.runtimePluginSelections,
         })
       : inboundPluginRegistry;
diff --git a/src/agents/prepared-model-runtime.plugin-context.test.ts b/src/agents/prepared-model-runtime.plugin-context.test.ts
index 0fda939928cf..721c4dee9b89 100644
--- a/src/agents/prepared-model-runtime.plugin-context.test.ts
+++ b/src/agents/prepared-model-runtime.plugin-context.test.ts
@@ -36,7 +36,7 @@ describe("prepared model runtime plugin metadata ownership", () => {
       inlineProviderModels: [],
       pluginMetadataSnapshot: gatewaySnapshot,
     };
-    const resolveMetadata = vi.spyOn(pluginMetadata, "loadPluginMetadataSnapshot");
+    const resolveMetadata = vi.spyOn(pluginMetadata, "resolvePluginMetadataSnapshot");
     const getCurrentMetadata = vi.spyOn(currentPluginMetadata, "getCurrentPluginMetadataSnapshot");
 
     try {
diff --git a/src/agents/prepared-model-runtime.plugin-context.ts b/src/agents/prepared-model-runtime.plugin-context.ts
index dc197cbfc7df..ee5d1a85de2d 100644
--- a/src/agents/prepared-model-runtime.plugin-context.ts
+++ b/src/agents/prepared-model-runtime.plugin-context.ts
@@ -74,9 +74,8 @@ function resolveColdMetadataSnapshot(
   input: PreparedModelRuntimeInput,
   env: NodeJS.ProcessEnv,
 ): PluginMetadataSnapshot {
-  // Resolve (slot-probing) instead of load: in the gateway the published current
-  // generation satisfies this read, which keeps snapshot identity stable for the
-  // generation-bound registry reuse in the inbound loader.
+  // Slot probing preserves the published Gateway generation identity; cold callers
+  // still fall through to a fresh metadata load.
   const resolvedMetadataSnapshot = resolvePluginMetadataSnapshot({
     config: input.config,
     env,
diff --git a/src/agents/prepared-model-runtime.startup-static.test.ts b/src/agents/prepared-model-runtime.startup-static.test.ts
index 5d26256dfaaf..b50c741f3ef0 100644
--- a/src/agents/prepared-model-runtime.startup-static.test.ts
+++ b/src/agents/prepared-model-runtime.startup-static.test.ts
@@ -407,9 +407,8 @@ describe("prepared model runtime Gateway catalog mode", () => {
     );
     expect(mocks.buildPreparedModelCatalogSnapshot).not.toHaveBeenCalled();
     expect(mocks.loadStaticCatalog).not.toHaveBeenCalled();
-    // Two slot-probing resolutions share the published generation: the prepared
-    // cold plugin context and the model-id normalization lane. Neither builds a
-    // catalog; the laziness guards above are the eager-work protections.
+    // The prepared plugin context and model-id normalization probe the same
+    // published metadata generation without starting catalog discovery.
     expect(mocks.resolvePluginMetadataSnapshot).toHaveBeenCalledTimes(2);
     expect(configuredRuntimeModelCount).toBe(1);
     expect(generatedCatalogReadCount).toBe(0);
diff --git a/src/agents/runtime-plugins.test.ts b/src/agents/runtime-plugins.test.ts
index 262abc227b33..f20e76e37bac 100644
--- a/src/agents/runtime-plugins.test.ts
+++ b/src/agents/runtime-plugins.test.ts
@@ -122,34 +122,36 @@ describe("agent runtime plugin registries", () => {
     );
   });
 
-  it("reuses the Gateway inbound registry and loads only its selected provider delta", () => {
+  it("reuses the current Gateway generation and loads only the imported-plugin delta", () => {
     const config = {} as never;
-    const gatewayPlugin = {
-      id: "gateway-owned",
-      origin: "bundled",
-      rootDir: "/dist/extensions/gateway-owned",
-      source: "/dist/extensions/gateway-owned/index.js",
-      status: "loaded",
+    const workspaceDir = "/tmp/default-workspace";
+    const activeRegistry = {
+      plugins: [
+        { id: "gateway-owned", origin: "bundled", status: "loaded" },
+        {
+          id: "deferred",
+          origin: "bundled",
+          status: "loaded",
+          format: "openclaw",
+          imported: false,
+        },
+      ],
     };
-    const activeRegistry = { plugins: [gatewayPlugin] };
-    const selectedRegistry = { plugins: [gatewayPlugin, { id: "selected-provider" }] };
     const metadataSnapshot = {
-      ...createMetadataSnapshot("/tmp/default-workspace", undefined),
+      ...createMetadataSnapshot(workspaceDir, undefined),
       manifestRegistry: {
         diagnostics: [],
         plugins: [
-          {
-            id: "gateway-owned",
-            origin: "bundled",
-            rootDir: "/extensions/gateway-owned",
-            source: "/extensions/gateway-owned/index.ts",
-          },
+          { id: "gateway-owned", origin: "bundled" },
+          { id: "deferred", origin: "bundled" },
         ],
       },
     };
+    const selectedRegistry = { plugins: [...activeRegistry.plugins, { id: "selected-provider" }] };
     hoisted.getActivePluginRegistry.mockReturnValue(activeRegistry);
+    hoisted.getActivePluginRegistryWorkspaceDir.mockReturnValue(workspaceDir);
     hoisted.getActivePluginRuntimeSubagentMode.mockReturnValue("gateway-bindable");
-    hoisted.getCurrentPluginMetadataSnapshot.mockImplementation(() => metadataSnapshot);
+    hoisted.getCurrentPluginMetadataSnapshot.mockReturnValue(metadataSnapshot);
     hoisted.loadPluginRegistryHandle.mockReturnValue(selectedRegistry);
     hoisted.resolveAgentRuntimePluginLoadPlan.mockImplementation(({ basePluginIds }) => ({
       config,
@@ -162,71 +164,82 @@ describe("agent runtime plugin registries", () => {
         allowGatewaySubagentBinding: true,
         config,
         runtimePluginSelections: [{ provider: "selected", modelId: "model" }],
-        workspaceDir: "/tmp/default-workspace",
+        workspaceDir,
       },
       metadataSnapshot as never,
       createPreparedInboundRegistryLoader(),
+      true,
     );
 
     expect(prepared.inboundPluginRegistry).toBe(activeRegistry);
     expect(prepared.runtimePluginRegistry).toBe(selectedRegistry);
+    expect(hoisted.resolveAgentRuntimePluginLoadPlan).toHaveBeenCalledWith(
+      expect.objectContaining({ basePluginIds: ["gateway-owned"] }),
+    );
     expect(hoisted.loadPluginRegistryHandle).toHaveBeenCalledOnce();
     expect(hoisted.loadPluginRegistryHandle).toHaveBeenCalledWith(
       expect.objectContaining({
         onlyPluginIds: ["gateway-owned", "selected-provider"],
+        preferBuiltPluginArtifacts: true,
       }),
     );
   });
 
-  it("refuses Gateway registry reuse for a non-current metadata generation", () => {
+  it.each([
+    {
+      name: "custom environment",
+      input: { env: { OPENCLAW_STATE_DIR: "/tmp/custom-state" } },
+    },
+    {
+      name: "non-bindable mode",
+      setup: () => hoisted.getActivePluginRuntimeSubagentMode.mockReturnValue("default"),
+    },
+    {
+      name: "different workspace",
+      setup: () => hoisted.getActivePluginRegistryWorkspaceDir.mockReturnValue("/tmp/other"),
+    },
+    {
+      name: "stale metadata generation",
+      setup: () => hoisted.getCurrentPluginMetadataSnapshot.mockReturnValue({}),
+    },
+    {
+      name: "manifest mismatch",
+      setup: (activeRegistry: { plugins: Array<{ origin: string }> }) => {
+        activeRegistry.plugins[0]!.origin = "external";
+      },
+    },
+  ])("refuses Gateway registry reuse for $name", ({ input, setup }) => {
     const config = {} as never;
-    const gatewayPlugin = {
-      id: "gateway-owned",
-      origin: "bundled",
-      rootDir: "/dist/extensions/gateway-owned",
-      source: "/dist/extensions/gateway-owned/index.js",
-      status: "loaded",
+    const workspaceDir = "/tmp/default-workspace";
+    const activeRegistry = {
+      plugins: [{ id: "gateway-owned", origin: "bundled", status: "loaded" }],
     };
-    const activeRegistry = { plugins: [gatewayPlugin] };
     const metadataSnapshot = {
-      ...createMetadataSnapshot("/tmp/default-workspace", undefined),
+      ...createMetadataSnapshot(workspaceDir, undefined),
       manifestRegistry: {
         diagnostics: [],
-        plugins: [
-          {
-            id: "gateway-owned",
-            origin: "bundled",
-            rootDir: "/extensions/gateway-owned",
-            source: "/extensions/gateway-owned/index.ts",
-          },
-        ],
+        plugins: [{ id: "gateway-owned", origin: "bundled" }],
       },
     };
     hoisted.getActivePluginRegistry.mockReturnValue(activeRegistry);
+    hoisted.getActivePluginRegistryWorkspaceDir.mockReturnValue(workspaceDir);
     hoisted.getActivePluginRuntimeSubagentMode.mockReturnValue("gateway-bindable");
-    // A different (older/leaked) generation is current: identity must fail closed.
-    hoisted.getCurrentPluginMetadataSnapshot.mockReturnValue(
-      createMetadataSnapshot("/tmp/default-workspace", undefined),
-    );
-    hoisted.loadPluginRegistryHandle.mockReturnValue({ plugins: [] });
-    hoisted.resolveAgentRuntimePluginLoadPlan.mockImplementation(({ basePluginIds }) => ({
-      config,
-      pluginIds: basePluginIds,
-    }));
+    hoisted.getCurrentPluginMetadataSnapshot.mockReturnValue(metadataSnapshot);
+    setup?.(activeRegistry);
 
-    const loadInboundRegistry = createPreparedInboundRegistryLoader();
-    const inbound = loadInboundRegistry(
+    const inbound = createPreparedInboundRegistryLoader()(
       {
         agentDir: "/tmp/agent",
         allowGatewaySubagentBinding: true,
         config,
-        workspaceDir: "/tmp/default-workspace",
+        workspaceDir,
+        ...input,
       },
       metadataSnapshot as never,
     );
 
     expect(inbound).not.toBe(activeRegistry);
-    expect(hoisted.loadPluginRegistryHandle).toHaveBeenCalled();
+    expect(hoisted.loadPluginRegistryHandle).toHaveBeenCalledOnce();
   });
 
   it("keeps direct no-current loads on the requested workspace", () => {

From 2213d569ceef780299b06fa2460b02a365a8ea8f Mon Sep 17 00:00:00 2001
From: Ayaan Gazali <ayaangazali.work@gmail.com>
Date: Fri, 21 Aug 2026 11:52:00 -0700
Subject: [PATCH 067/124] fix(ui): clear terminal session activity indicators
 (#120327)

Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 ui/src/components/app-sidebar-render.ts        |  3 ++-
 .../app-sidebar-session-catalog-render.ts      |  3 ++-
 ...pp-sidebar-session-navigation-logic.test.ts | 18 ++++++++++++++++++
 .../app-sidebar-session-navigation-logic.ts    |  2 +-
 ui/src/components/lobster-pet-contract.ts      |  5 +++--
 ui/src/components/lobster-pet.test.ts          |  5 +++++
 .../components/chat-swarm-progress.test.ts     | 15 +++++++++++++++
 .../chat/components/chat-swarm-progress.ts     |  3 ++-
 8 files changed, 48 insertions(+), 6 deletions(-)

diff --git a/ui/src/components/app-sidebar-render.ts b/ui/src/components/app-sidebar-render.ts
index 40d4d03e7542..ff95c1c03b0c 100644
--- a/ui/src/components/app-sidebar-render.ts
+++ b/ui/src/components/app-sidebar-render.ts
@@ -21,6 +21,7 @@ import {
   presenceViewerLabel,
   projectOnlinePresenceViewers,
 } from "../lib/presence-users.ts";
+import { isSessionRunActive } from "../lib/session-run-state.ts";
 import {
   resolveSessionPreferredFace,
   sessionNavigationTarget,
@@ -178,7 +179,7 @@ export function renderAppSidebarHomeRow(host: AppSidebarRenderHost) {
     isSessionRouteId(host.activeRouteId) &&
     areUiSessionKeysEquivalent(host.getRouteSessionKey(), mainKey);
   const hasComposerDraft = host.hasSessionDraft(mainKey);
-  const running = mainRow?.hasActiveRun === true;
+  const running = mainRow ? isSessionRunActive(mainRow) : false;
   const unread = mainRow?.unread === true && !active;
   // Home keeps its page/attention glyph leading and shares trailing activity with session rows.
   const homeGlyph = renderSessionGlyph({
diff --git a/ui/src/components/app-sidebar-session-catalog-render.ts b/ui/src/components/app-sidebar-session-catalog-render.ts
index 6fe724fa2d61..fefca67400d3 100644
--- a/ui/src/components/app-sidebar-session-catalog-render.ts
+++ b/ui/src/components/app-sidebar-session-catalog-render.ts
@@ -11,6 +11,7 @@ import { t } from "../i18n/index.ts";
 import { formatUiError } from "../lib/format-error.ts";
 import { handleContextMenuEvent } from "../lib/keyboard-shortcuts.ts";
 import { shouldHandleNavigationClick } from "../lib/navigation-click.ts";
+import { isSessionRunActive } from "../lib/session-run-state.ts";
 import type { CatalogSessionKey } from "../lib/sessions/catalog-key.ts";
 import { buildCatalogSessionKey } from "../lib/sessions/catalog-key.ts";
 import {
@@ -140,7 +141,7 @@ export function renderSessionCatalogGroups(params: SessionCatalogGroupsParams) {
       const row = session.sessionKey ? liveRowsByKey.get(session.sessionKey) : undefined;
       return row ? [row] : [];
     });
-    const hasActiveRun = liveRows.some((row) => row.hasActiveRun === true);
+    const hasActiveRun = liveRows.some(isSessionRunActive);
     const hasUnread = liveRows.some((row) => row.unread === true);
     const hasBrandIcon = hasProviderBrandIcon(catalog.id);
     const loadingMore = params.loadingMoreCatalogIds.has(catalog.id);
diff --git a/ui/src/components/app-sidebar-session-navigation-logic.test.ts b/ui/src/components/app-sidebar-session-navigation-logic.test.ts
index 67ae94acacbe..5520f6270295 100644
--- a/ui/src/components/app-sidebar-session-navigation-logic.test.ts
+++ b/ui/src/components/app-sidebar-session-navigation-logic.test.ts
@@ -1,10 +1,12 @@
 import { describe, expect, it, vi } from "vitest";
 import type { GatewaySessionRow, SessionsListResult } from "../api/types.ts";
+import { t } from "../i18n/index.ts";
 import { createTestGatewayClient } from "../test-helpers/gateway-client.ts";
 import { collectKnownSessionRows, fetchSessionLineage } from "./app-sidebar-child-session-data.ts";
 import {
   buildSidebarSessionNavigationState,
   compareSidebarSessionRowsByMode,
+  resolveSidebarAgentChipSubtitle,
 } from "./app-sidebar-session-navigation-logic.ts";
 import { projectSessionTree } from "./app-sidebar-session-tree.ts";
 import type { SidebarRecentSession } from "./app-sidebar-session-types.ts";
@@ -177,6 +179,22 @@ describe("sidebar session live-run projection", () => {
     },
   );
 
+  it("stops calling a completed registry-active agent Working", () => {
+    const session = {
+      key: "agent:main:main",
+      kind: "direct",
+      updatedAt: 1,
+      hasActiveRun: true,
+    } satisfies GatewaySessionRow;
+
+    expect(resolveSidebarAgentChipSubtitle({ ...session, status: "done" })).not.toBe(
+      t("agentChip.working"),
+    );
+    expect(resolveSidebarAgentChipSubtitle({ ...session, status: "running" })).toBe(
+      t("agentChip.working"),
+    );
+  });
+
   it("carries active cloud disk pressure into the existing sidebar badge model", () => {
     const projected = projectSidebarSession({
       placement: {
diff --git a/ui/src/components/app-sidebar-session-navigation-logic.ts b/ui/src/components/app-sidebar-session-navigation-logic.ts
index 40e997668ad3..b22d8beda1ea 100644
--- a/ui/src/components/app-sidebar-session-navigation-logic.ts
+++ b/ui/src/components/app-sidebar-session-navigation-logic.ts
@@ -557,7 +557,7 @@ export function resolveSidebarAgentResumeKey(
 }
 
 export function resolveSidebarAgentChipSubtitle(latest: SessionRow | null): string {
-  if (latest?.hasActiveRun) {
+  if (latest && isSessionRunActive(latest)) {
     return t("agentChip.working");
   }
   return latest ? resolveSessionDisplayName(latest.key, latest) : t("agentChip.ready");
diff --git a/ui/src/components/lobster-pet-contract.ts b/ui/src/components/lobster-pet-contract.ts
index 1dadb734b5a7..cb72e6f75806 100644
--- a/ui/src/components/lobster-pet-contract.ts
+++ b/ui/src/components/lobster-pet-contract.ts
@@ -1,5 +1,6 @@
 import type { SessionRunStatus } from "../../../packages/gateway-protocol/src/schema/sessions-row.js";
 import { fnv1aUtf16 } from "../lib/fnv1a.ts";
+import { isSessionRunActive } from "../lib/session-run-state.ts";
 
 export type LobsterPetMode = "idle" | "busy" | "offline";
 
@@ -159,10 +160,10 @@ export function resolveLobsterRunOutcome(
 
 export function resolveLobsterPetMode(
   connected: boolean,
-  sessions: ReadonlyArray<{ hasActiveRun?: boolean | null }> | null | undefined,
+  sessions: ReadonlyArray<{ hasActiveRun?: boolean; status?: SessionRunStatus }> | null | undefined,
 ): LobsterPetMode {
   if (!connected) {
     return "offline";
   }
-  return sessions?.some((row) => row.hasActiveRun === true) ? "busy" : "idle";
+  return sessions?.some(isSessionRunActive) ? "busy" : "idle";
 }
diff --git a/ui/src/components/lobster-pet.test.ts b/ui/src/components/lobster-pet.test.ts
index 8049bc19b95e..ed1758780b6f 100644
--- a/ui/src/components/lobster-pet.test.ts
+++ b/ui/src/components/lobster-pet.test.ts
@@ -169,6 +169,11 @@ describe("resolveLobsterPetMode", () => {
       "busy",
     );
   });
+
+  it("stops looking busy after a registry-active run reaches a terminal status", () => {
+    expect(resolveLobsterPetMode(true, [{ status: "done", hasActiveRun: true }])).toBe("idle");
+    expect(resolveLobsterPetMode(true, [{ status: "running", hasActiveRun: true }])).toBe("busy");
+  });
 });
 
 describe("resolveLobsterRunOutcome", () => {
diff --git a/ui/src/pages/chat/components/chat-swarm-progress.test.ts b/ui/src/pages/chat/components/chat-swarm-progress.test.ts
index 55cfddc7d517..2edbbbb1a138 100644
--- a/ui/src/pages/chat/components/chat-swarm-progress.test.ts
+++ b/ui/src/pages/chat/components/chat-swarm-progress.test.ts
@@ -105,6 +105,21 @@ describe("chat Swarm progress", () => {
     expect(container.querySelector("[data-test-id=chat-swarm]")).toBeNull();
   });
 
+  it("keeps registry-active terminal workers completed and hides finished groups", () => {
+    const running = session({ key: "running", status: "running" });
+    const completed = session({ key: "completed", status: "done", hasActiveRun: true });
+    const failed = session({ key: "failed", status: "failed", hasActiveRun: true });
+    const container = renderProgress([running, completed, failed]);
+
+    expect(container.textContent?.replace(/\s+/g, " ")).toContain("1 Running · 1 Done · 1 Failed");
+
+    render(
+      renderChatSwarmProgress({ sessionKey: parentSessionKey, sessions: [completed, failed] }),
+      container,
+    );
+    expect(container.querySelector("[data-test-id=chat-swarm]")).toBeNull();
+  });
+
   it("buckets children by phase, labels the default bucket, and shows the latest log", () => {
     const container = renderProgress([
       session({ key: "unphased", label: "Older child", status: "running" }),
diff --git a/ui/src/pages/chat/components/chat-swarm-progress.ts b/ui/src/pages/chat/components/chat-swarm-progress.ts
index 722f3ab63160..2d07f2219240 100644
--- a/ui/src/pages/chat/components/chat-swarm-progress.ts
+++ b/ui/src/pages/chat/components/chat-swarm-progress.ts
@@ -1,6 +1,7 @@
 import { html, nothing, type TemplateResult } from "lit";
 import type { GatewaySessionRow } from "../../../api/types.ts";
 import { t } from "../../../i18n/index.ts";
+import { isSessionRunActive } from "../../../lib/session-run-state.ts";
 import { areUiSessionKeysEquivalent } from "../../../lib/sessions/session-key.ts";
 
 type SwarmDotStatus = "queued" | "running" | "done" | "failed";
@@ -53,7 +54,7 @@ function swarmDotStatus(row: GatewaySessionRow): SwarmDotStatus | null {
   if (row.status === "queued") {
     return "queued";
   }
-  if (row.status === "running" || row.hasActiveRun === true) {
+  if (isSessionRunActive(row)) {
     return "running";
   }
   if (row.status === "done") {

From 3df8ba2eb1cd33c491429da056ce2045b2733110 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 11:54:59 -0700
Subject: [PATCH 068/124] perf(agents): avoid full roster projection for point
 lookups (#127384)

Co-authored-by: Amp <amp@ampcode.com>
---
 src/agents/agent-scope-config.test.ts | 19 +++++++++++++++
 src/agents/agent-scope-config.ts      | 35 ++++++++++++++++++++-------
 2 files changed, 45 insertions(+), 9 deletions(-)

diff --git a/src/agents/agent-scope-config.test.ts b/src/agents/agent-scope-config.test.ts
index 9e735d4b2eec..ed02b3ab9b2e 100644
--- a/src/agents/agent-scope-config.test.ts
+++ b/src/agents/agent-scope-config.test.ts
@@ -223,6 +223,25 @@ describe("agent roster resolution", () => {
     expect(resolveAgentConfig({ agents: { defaults, list: [] } }, "main")).toBeUndefined();
   });
 
+  it("does not project unrelated keyed entries while resolving one agent", () => {
+    let unrelatedEntryReads = 0;
+    const entries = new Proxy(
+      { main: { name: "Primary" }, worker: { name: "Worker" } },
+      {
+        get(target, property, receiver) {
+          if (property === "worker") {
+            unrelatedEntryReads += 1;
+          }
+          return Reflect.get(target, property, receiver);
+        },
+      },
+    );
+    const config = { agents: { ownership: "explicit" as const, entries } };
+
+    expect(resolveAgentConfig(config, "main")?.name).toBe("Primary");
+    expect(unrelatedEntryReads).toBe(0);
+  });
+
   it("keeps the retained legacy owner on the inherited workspace before config write", () => {
     const cfg = migratePersistedImplicitMainRoster({
       agents: {
diff --git a/src/agents/agent-scope-config.ts b/src/agents/agent-scope-config.ts
index 547f1a69a2d0..1b8549788c8a 100644
--- a/src/agents/agent-scope-config.ts
+++ b/src/agents/agent-scope-config.ts
@@ -1,5 +1,6 @@
 /** Resolves configured agent ids, directories, workspaces, and merged agent defaults. */
 import path from "node:path";
+import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import {
   normalizeOptionalString,
   readStringValue,
@@ -94,17 +95,12 @@ function stripNullBytes(s: string): string {
 /** Lists valid configured agent entries from config. */
 export function listAgentEntriesWithSource(cfg: OpenClawConfig): ListedAgentEntry[] {
   const roster = readAgentRosterProperty(cfg);
-  if (
-    roster?.kind === "entries" &&
-    roster.value &&
-    typeof roster.value === "object" &&
-    !Array.isArray(roster.value)
-  ) {
+  if (roster?.kind === "entries" && isRecord(roster.value)) {
     return Object.entries(roster.value).flatMap(([id, entry]) =>
-      entry !== null && typeof entry === "object" && !Array.isArray(entry)
+      isRecord(entry)
         ? [
             {
-              entry: { ...(entry as Omit<AgentEntry, "id">), id },
+              entry: { ...entry, id },
               source: { kind: "entries" as const, key: id },
             },
           ]
@@ -286,7 +282,28 @@ export function tryResolveDefaultAgentId(cfg: OpenClawConfig): string | undefine
 
 export function resolveAgentEntry(cfg: OpenClawConfig, agentId: string): AgentEntry | undefined {
   const id = normalizeAgentId(agentId);
-  return listAgentEntries(cfg).find((entry) => normalizeAgentId(entry.id) === id);
+  // Point lookups are hot; the public list helper must clone every keyed entry.
+  // Traverse the roster directly so a match does not project unrelated agents.
+  const roster = readAgentRosterProperty(cfg);
+  if (roster?.kind === "entries" && isRecord(roster.value)) {
+    const entries = roster.value;
+    for (const key in entries) {
+      if (!Object.hasOwn(entries, key)) {
+        continue;
+      }
+      const entry = entries[key];
+      if (isRecord(entry) && normalizeAgentId(key) === id) {
+        return { ...entry, id: key };
+      }
+    }
+    return undefined;
+  }
+  if (roster?.kind === "list" && Array.isArray(roster.value)) {
+    return (roster.value as AgentEntry[]).find(
+      (entry) => entry !== null && typeof entry === "object" && normalizeAgentId(entry.id) === id,
+    );
+  }
+  return undefined;
 }
 
 /** Resolves the authored entry object for in-place canonical config mutations. */

From 6aced3350d4256965676cbe3cc5cbe4733e14cff Mon Sep 17 00:00:00 2001
From: Sasan <sasan1200@gmail.com>
Date: Fri, 21 Aug 2026 14:59:55 -0400
Subject: [PATCH 069/124] fix(ui): Model Providers usage cards stay empty after
 a failed usage.status (#120301)

* fix(ui): recover provider usage after transient gateway failures

Keep failed provider-usage Results cold across Models and Usage direct and preloaded paths. Preserve canonical Gateway lifecycle ownership, request epochs, and route provenance.

Co-authored-by: Sasan Sotoodehfar <sasan1200@gmail.com>

* test(ui): shrink provider assertion safety baseline

Drop the obsolete grandfathered non-null assertion after moving provider probe-result policy into its owner.

Co-authored-by: Sasan Sotoodehfar <sasan1200@gmail.com>

* test(ui): tolerate browser font geometry rounding

Match existing chat-layout two-pixel renderer tolerance on both completed-work spacing boundaries.

Co-authored-by: Sasan Sotoodehfar <sasan1200@gmail.com>

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 config/assertion-safety-baseline.txt          |   1 -
 .../chat/chat-responsive.browser.test.ts      |   6 +-
 .../pages/gateway-source-replacement.test.ts  | 110 +++++++-
 .../model-providers-page.test.ts              | 236 +++++++++++++++++-
 .../model-providers/model-providers-page.ts   | 209 ++++++++--------
 ui/src/pages/model-providers/probe-results.ts |  41 +++
 ui/src/pages/model-providers/route.ts         |  27 +-
 ui/src/pages/route-provenance.test.ts         |  11 +-
 ui/src/pages/usage/refresh-policy.ts          |   4 -
 ui/src/pages/usage/usage-page.test.ts         |  63 +++++
 ui/src/pages/usage/usage-page.ts              |   4 +-
 11 files changed, 583 insertions(+), 129 deletions(-)
 create mode 100644 ui/src/pages/model-providers/probe-results.ts

diff --git a/config/assertion-safety-baseline.txt b/config/assertion-safety-baseline.txt
index 915e4fe0cddf..d0f22e2d1c9a 100644
--- a/config/assertion-safety-baseline.txt
+++ b/config/assertion-safety-baseline.txt
@@ -4249,7 +4249,6 @@ ui/src/pages/logs/log-lines.ts	1
 ui/src/pages/logs/view.ts	2
 ui/src/pages/memory-import/view.ts	3
 ui/src/pages/model-providers/default-models-view.ts	1
-ui/src/pages/model-providers/model-providers-page.ts	1
 ui/src/pages/model-providers/view.ts	3
 ui/src/pages/model-setup/provider-picker.ts	3
 ui/src/pages/model-setup/view.ts	2
diff --git a/ui/src/pages/chat/chat-responsive.browser.test.ts b/ui/src/pages/chat/chat-responsive.browser.test.ts
index 12be9b32b605..8cbb945e857b 100644
--- a/ui/src/pages/chat/chat-responsive.browser.test.ts
+++ b/ui/src/pages/chat/chat-responsive.browser.test.ts
@@ -1299,9 +1299,9 @@ describeBrowserLayout.concurrent("chat responsive browser layout", () => {
         };
       });
 
-      // Browser font metrics can shift subpixel geometry; one CSS pixel is the layout boundary.
-      expect(Math.abs(gaps.before - expectedGap)).toBeLessThan(1);
-      expect(Math.abs(gaps.after - expectedGap)).toBeLessThan(1);
+      // Browser font metrics can shift subpixel geometry by up to two CSS pixels.
+      expect(Math.abs(gaps.before - expectedGap)).toBeLessThanOrEqual(2);
+      expect(Math.abs(gaps.after - expectedGap)).toBeLessThanOrEqual(2);
     } finally {
       await closeBrowserPage(page);
     }
diff --git a/ui/src/pages/gateway-source-replacement.test.ts b/ui/src/pages/gateway-source-replacement.test.ts
index 538e468aaac0..462c2bb1489f 100644
--- a/ui/src/pages/gateway-source-replacement.test.ts
+++ b/ui/src/pages/gateway-source-replacement.test.ts
@@ -7,6 +7,8 @@ import type { GatewayBrowserClient } from "../api/gateway.ts";
 import type { ApplicationContext, ApplicationGatewaySnapshot } from "../app/context.ts";
 import { clawhubVerdictKey } from "../lib/skills/index.ts";
 import { waitForFast } from "../test-helpers/wait-for.ts";
+import type { ModelProvidersData } from "./model-providers/load.ts";
+import type { ModelProvidersRouteData } from "./model-providers/route.ts";
 import type { SessionsRouteData } from "./sessions/route.ts";
 import type { SkillsRouteData } from "./skills/skills-page.ts";
 import { createSkill } from "./skills/view.test-support.ts";
@@ -15,6 +17,7 @@ import type { UsageRouteData } from "./usage/usage-page.ts";
 import "./cron/cron-page.ts";
 import "./debug/debug-page.ts";
 import "./logs/logs-page.ts";
+import "./model-providers/model-providers-page.ts";
 import "./sessions/sessions-page.ts";
 import "./skills/skills-page.ts";
 import "./tasks/tasks-page.ts";
@@ -83,6 +86,7 @@ function contextWithClient(
     connected?: boolean;
     agentsList?: unknown;
     ensureList?: () => Promise<unknown>;
+    selectedAgentId?: string | null;
   } = {},
 ): ApplicationContext {
   const subscribe = () => () => undefined;
@@ -97,13 +101,24 @@ function contextWithClient(
     },
     agentIdentity: { get: () => undefined, ensure: vi.fn(async () => undefined), subscribe },
     agentSelection: {
-      state: { selectedId: null, scopeId: null },
+      state: {
+        selectedId: options.selectedAgentId ?? null,
+        scopeId: options.selectedAgentId ?? null,
+      },
       set: vi.fn(),
       setScope: vi.fn(),
       subscribe,
     },
     channels: { subscribe },
-    runtimeConfig: { state: { configSnapshot: null }, subscribe },
+    runtimeConfig: {
+      state: { configSnapshot: {}, configLoading: false },
+      ensureLoaded: vi.fn(async () => undefined),
+      subscribe,
+    },
+    overlays: {
+      snapshot: { updateRunning: false, updateReconciliationPending: false },
+      subscribe,
+    },
     sessions: {
       state: { result: null, loading: false },
       list: vi.fn(async () => null),
@@ -157,7 +172,7 @@ function createPage(tagName: string, context: ApplicationContext): TestPage {
 async function replaceContext(
   page: TestPage,
   replacementClient: GatewayBrowserClient,
-  options: { connected?: boolean; agentsList?: unknown } = {},
+  options: { connected?: boolean; agentsList?: unknown; selectedAgentId?: string | null } = {},
 ): Promise<void> {
   page.remove();
   page.context = contextWithClient(replacementClient, options);
@@ -297,7 +312,7 @@ describe("gateway source replacement across reconnect with a reused client", ()
       },
       result,
       costSummary: null,
-      providerUsage: null,
+      providerUsage: { ok: true, value: { updatedAt: 1, providers: [] } },
       loadedAtMs: Date.now(),
       error: null,
     };
@@ -404,7 +419,7 @@ describe("gateway source replacement across reconnect with a reused client", ()
       },
       result,
       costSummary: null,
-      providerUsage: null,
+      providerUsage: { ok: true, value: { updatedAt: 1, providers: [] } },
       loadedAtMs: Date.now(),
       error: null,
     };
@@ -446,6 +461,91 @@ describe("gateway source replacement across reconnect with a reused client", ()
     await waitForFast(() => expect(request).toHaveBeenCalledTimes(12));
     await waitForFast(() => expect(page.usageLoading).toBe(false));
   });
+
+  it("discards Model Providers work from a replaced source that reuses its client", async () => {
+    const staleAuth = deferred<unknown>();
+    let authCalls = 0;
+    const request = vi.fn(async (method: string) => {
+      if (method === "models.authStatus") {
+        authCalls += 1;
+        return authCalls === 1 ? staleAuth.promise : { ts: 2, providers: [] };
+      }
+      if (method === "models.list") {
+        return { models: [] };
+      }
+      if (method === "config.get") {
+        return { config: {}, hash: "hash" };
+      }
+      if (method === "usage.status") {
+        return { updatedAt: 2, providers: [] };
+      }
+      if (method === "sessions.usage") {
+        return { aggregates: { byProvider: [] } };
+      }
+      return {};
+    });
+    const client = { request } as unknown as GatewayBrowserClient;
+    const agentsList = { defaultId: "main", agents: [{ id: "main" }] };
+    const page = createPage(
+      "openclaw-model-providers-page",
+      contextWithClient(client, { connected: true, agentsList, selectedAgentId: "main" }),
+    ) as TestPage & { data: ModelProvidersData | null };
+    document.body.append(page);
+    await waitForFast(() => expect(authCalls).toBe(1));
+
+    await replaceContext(page, client, { connected: true, agentsList, selectedAgentId: "main" });
+    await waitForFast(() => expect(page.data?.authStatus?.ts).toBe(2));
+
+    staleAuth.resolve({ ts: 1, providers: [] });
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(page.data?.authStatus?.ts).toBe(2);
+  });
+
+  it("rejects Model Providers route data from an earlier same-client gateway epoch", async () => {
+    const request = vi.fn(async (method: string) => {
+      if (method === "models.authStatus") {
+        return { ts: 2, providers: [] };
+      }
+      if (method === "models.list") {
+        return { models: [] };
+      }
+      if (method === "config.get") {
+        return { config: {}, hash: "fresh" };
+      }
+      if (method === "usage.status") {
+        return { updatedAt: 2, providers: [] };
+      }
+      if (method === "sessions.usage") {
+        return { aggregates: { byProvider: [] } };
+      }
+      return {};
+    });
+    const client = { request } as unknown as GatewayBrowserClient;
+    const agentsList = { defaultId: "main", agents: [{ id: "main" }] };
+    const context = contextWithClient(client, {
+      connected: true,
+      agentsList,
+      selectedAgentId: "main",
+    });
+    const staleData = { authStatus: { ts: 1, providers: [] } } as unknown as ModelProvidersData;
+    const page = createPage("openclaw-model-providers-page", context) as TestPage & {
+      routeData: ModelProvidersRouteData;
+      data: ModelProvidersData | null;
+    };
+    page.routeData = {
+      gateway: context.gateway,
+      gatewaySnapshot: { ...context.gateway.snapshot },
+      data: staleData,
+      client,
+      agentId: "main",
+    };
+
+    document.body.append(page);
+    await waitForFast(() => expect(page.data?.authStatus?.ts).toBe(2));
+    expect(page.data).not.toBe(staleData);
+  });
+
   it("preserves matching skills route data on the first bind", async () => {
     const request = vi.fn();
     const client = { request } as unknown as GatewayBrowserClient;
diff --git a/ui/src/pages/model-providers/model-providers-page.test.ts b/ui/src/pages/model-providers/model-providers-page.test.ts
index 0b8f98d61e17..958be433ed7f 100644
--- a/ui/src/pages/model-providers/model-providers-page.test.ts
+++ b/ui/src/pages/model-providers/model-providers-page.test.ts
@@ -7,7 +7,7 @@ import type { ApplicationContext, ApplicationGatewaySnapshot } from "../../app/c
 import { waitForFast } from "../../test-helpers/wait-for.ts";
 import type { DefaultModelSelection, ModelProviderLogoutTarget } from "./data.ts";
 import { EMPTY_MODEL_PROVIDERS_DATA, type ModelProvidersData } from "./load.ts";
-import type { ModelProvidersRouteData } from "./model-providers-page.ts";
+import type { ModelProvidersRouteData } from "./route.ts";
 import "./model-providers-page.ts";
 
 type ModelProvidersPageTestElement = HTMLElement & {
@@ -27,6 +27,7 @@ type ModelProvidersPageTestElement = HTMLElement & {
   pendingLogoutProvider: string | null;
   probe: (cardId: string, providers: string[]) => Promise<void>;
   probeResults: Record<string, ModelsProbeResult>;
+  refresh: (opts: { force: boolean }) => Promise<void>;
   routeData: ModelProvidersRouteData | undefined;
   saveDefaultModels: () => Promise<void>;
   saveKey: (provider: string, configKey: string) => Promise<void>;
@@ -174,6 +175,32 @@ function createHarness(initialScopeId: string) {
   };
 }
 
+function publishableGateway(initial: ApplicationGatewaySnapshot) {
+  let current = initial;
+  const listeners = new Set<(value: ApplicationGatewaySnapshot) => void>();
+  return {
+    gateway: {
+      get snapshot() {
+        return current;
+      },
+      subscribe(listener: (value: ApplicationGatewaySnapshot) => void) {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+    },
+    publish(next: ApplicationGatewaySnapshot) {
+      current = next;
+      for (const listener of listeners) {
+        listener(next);
+      }
+    },
+  };
+}
+
+function requestCount(request: ReturnType<typeof vi.fn>, method: string): number {
+  return request.mock.calls.filter(([candidate]) => candidate === method).length;
+}
+
 function appendPage(context: ApplicationContext) {
   const page = document.createElement(
     "openclaw-model-providers-page",
@@ -189,6 +216,203 @@ afterEach(() => {
 });
 
 describe("ModelProvidersPage agent scope", () => {
+  it.each(["direct", "preload"] as const)(
+    "recovers a failed %s provider usage result on the next page activation",
+    async (loadSource) => {
+      const { context, request, snapshot } = createHarness("main");
+      vi.spyOn(document, "hasFocus").mockReturnValue(true);
+      vi.spyOn(document, "visibilityState", "get").mockReturnValue("visible");
+      const originalRequest = request.getMockImplementation()!;
+      let providerUnavailable = loadSource === "direct";
+      request.mockImplementation(async (method: string) => {
+        if (method === "usage.status" && providerUnavailable) {
+          throw new Error("provider usage unreachable");
+        }
+        return originalRequest(method);
+      });
+      const page = document.createElement(
+        "openclaw-model-providers-page",
+      ) as ModelProvidersPageTestElement;
+      page.context = context;
+      if (loadSource === "preload") {
+        const routeData = {
+          gateway: context.gateway,
+          gatewaySnapshot: snapshot,
+          data: {
+            ...EMPTY_MODEL_PROVIDERS_DATA,
+            config: {},
+            providerUsage: { ok: false as const, error: { kind: "request-failed" as const } },
+            updatedAt: Date.now(),
+          },
+          client: snapshot.client,
+          agentId: "main",
+        };
+        page.routeData = routeData;
+      }
+      document.body.append(page);
+      await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: false }));
+      const previousCalls = requestCount(request, "usage.status");
+      providerUnavailable = false;
+
+      window.dispatchEvent(new Event("focus"));
+
+      await vi.waitFor(() => {
+        expect(requestCount(request, "usage.status")).toBe(previousCalls + 1);
+      });
+      await vi.waitFor(() =>
+        expect(page.data?.providerUsage).toEqual({
+          ok: true,
+          value: { updatedAt: 1, providers: [] },
+        }),
+      );
+    },
+  );
+
+  it.each(["direct", "preload"] as const)(
+    "keeps a successful empty %s provider usage result fresh on page activation",
+    async (loadSource) => {
+      const { context, request, snapshot } = createHarness("main");
+      vi.spyOn(document, "hasFocus").mockReturnValue(true);
+      vi.spyOn(document, "visibilityState", "get").mockReturnValue("visible");
+      const page = document.createElement(
+        "openclaw-model-providers-page",
+      ) as ModelProvidersPageTestElement;
+      page.context = context;
+      if (loadSource === "preload") {
+        page.routeData = {
+          gateway: context.gateway,
+          gatewaySnapshot: snapshot,
+          data: {
+            ...EMPTY_MODEL_PROVIDERS_DATA,
+            config: {},
+            providerUsage: { ok: true, value: { updatedAt: 1, providers: [] } },
+            updatedAt: Date.now(),
+          },
+          client: snapshot.client,
+          agentId: "main",
+        };
+      }
+      document.body.append(page);
+      await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
+      const previousCalls = requestCount(request, "usage.status");
+
+      window.dispatchEvent(new Event("focus"));
+
+      expect(requestCount(request, "usage.status")).toBe(previousCalls);
+      expect(page.data?.providerUsage).toEqual({
+        ok: true,
+        value: { updatedAt: 1, providers: [] },
+      });
+    },
+  );
+
+  it("recovers a failed provider usage result after a same-client reconnect", async () => {
+    const { context, request, snapshot } = createHarness("main");
+    const source = publishableGateway(snapshot);
+    (context as { gateway: unknown }).gateway = source.gateway;
+    vi.spyOn(document, "hasFocus").mockReturnValue(true);
+    vi.spyOn(document, "visibilityState", "get").mockReturnValue("visible");
+    const originalRequest = request.getMockImplementation()!;
+    let providerUnavailable = true;
+    request.mockImplementation(async (method: string) => {
+      if (method === "usage.status" && providerUnavailable) {
+        throw new Error("provider usage unreachable");
+      }
+      return originalRequest(method);
+    });
+    const page = appendPage(context);
+    await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: false }));
+    providerUnavailable = false;
+
+    source.publish({ ...snapshot, phase: "reconnecting" });
+    source.publish({ ...snapshot, phase: "connected" });
+
+    await vi.waitFor(() => expect(requestCount(request, "usage.status")).toBe(2));
+    await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
+  });
+
+  it("defers failed provider usage recovery while hidden until page activation", async () => {
+    const { context, request, snapshot } = createHarness("main");
+    const source = publishableGateway(snapshot);
+    (context as { gateway: unknown }).gateway = source.gateway;
+    vi.spyOn(document, "hasFocus").mockReturnValue(true);
+    const visibility = vi.spyOn(document, "visibilityState", "get").mockReturnValue("hidden");
+    const originalRequest = request.getMockImplementation()!;
+    let providerUnavailable = true;
+    request.mockImplementation(async (method: string) => {
+      if (method === "usage.status" && providerUnavailable) {
+        throw new Error("provider usage unreachable");
+      }
+      return originalRequest(method);
+    });
+    const page = appendPage(context);
+    await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: false }));
+    providerUnavailable = false;
+
+    source.publish({ ...snapshot, phase: "reconnecting" });
+    source.publish({ ...snapshot, phase: "connected" });
+    expect(requestCount(request, "usage.status")).toBe(1);
+
+    visibility.mockReturnValue("visible");
+    document.dispatchEvent(new Event("visibilitychange"));
+
+    await vi.waitFor(() => expect(requestCount(request, "usage.status")).toBe(2));
+    await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
+  });
+
+  it("supersedes a hung load on disconnect so reconnect can replace it", async () => {
+    const { context, request, snapshot, deferNextAuthStatus } = createHarness("main");
+    const source = publishableGateway(snapshot);
+    (context as { gateway: unknown }).gateway = source.gateway;
+    vi.spyOn(document, "hasFocus").mockReturnValue(true);
+    vi.spyOn(document, "visibilityState", "get").mockReturnValue("visible");
+    const page = appendPage(context);
+    await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
+    deferNextAuthStatus();
+    void page.refresh({ force: true });
+    await vi.waitFor(() => expect(requestCount(request, "models.authStatus")).toBe(2));
+
+    source.publish({ ...snapshot, phase: "reconnecting" });
+    source.publish({ ...snapshot, phase: "connected" });
+
+    await vi.waitFor(() => expect(requestCount(request, "models.authStatus")).toBe(3));
+    await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
+  });
+
+  it("keeps direct data visible while a same-client reconnect replaces it", async () => {
+    const { context, deferNextAuthStatus, request, snapshot } = createHarness("main");
+    const source = publishableGateway(snapshot);
+    (context as { gateway: unknown }).gateway = source.gateway;
+    vi.spyOn(document, "hasFocus").mockReturnValue(true);
+    vi.spyOn(document, "visibilityState", "get").mockReturnValue("visible");
+    const page = appendPage(context);
+    await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
+    const previousData = page.data;
+    const originalRequest = request.getMockImplementation()!;
+    request.mockImplementation(async (method: string) => {
+      if (method === "config.get") {
+        return {
+          config: { agents: { defaults: { model: "openai/replacement-model" } } },
+          hash: "replacement-hash",
+        };
+      }
+      return originalRequest(method);
+    });
+    const release = deferNextAuthStatus();
+
+    source.publish({ ...snapshot, phase: "reconnecting" });
+    source.publish({ ...snapshot, phase: "connected" });
+    await vi.waitFor(() => expect(requestCount(request, "models.authStatus")).toBe(2));
+    expect(page.data).toBe(previousData);
+
+    release();
+    await vi.waitFor(() =>
+      expect(page.data?.config).toEqual({
+        agents: { defaults: { model: "openai/replacement-model" } },
+      }),
+    );
+  });
+
   it("switches application ownership from the concrete agent picker", async () => {
     const { agentSelection, context } = createHarness("main");
     const page = appendPage(context);
@@ -499,6 +723,8 @@ describe("ModelProvidersPage agent scope", () => {
     agentSelection.state.selectedId = "writer";
     agentSelection.state.scopeId = "writer";
     page.routeData = {
+      gateway: context.gateway,
+      gatewaySnapshot: snapshot,
       data: { ...EMPTY_MODEL_PROVIDERS_DATA, config: {}, updatedAt: 1 },
       client: snapshot.client,
       agentId: "writer",
@@ -632,7 +858,13 @@ describe("ModelProvidersPage agent scope", () => {
       "openclaw-model-providers-page",
     ) as ModelProvidersPageTestElement;
     page.context = context;
-    page.routeData = { data: staleData, client: snapshot.client, agentId: "main" };
+    page.routeData = {
+      gateway: context.gateway,
+      gatewaySnapshot: snapshot,
+      data: staleData,
+      client: snapshot.client,
+      agentId: "main",
+    };
     document.body.append(page);
 
     await waitForFast(() =>
diff --git a/ui/src/pages/model-providers/model-providers-page.ts b/ui/src/pages/model-providers/model-providers-page.ts
index 391279da9780..d2226961b629 100644
--- a/ui/src/pages/model-providers/model-providers-page.ts
+++ b/ui/src/pages/model-providers/model-providers-page.ts
@@ -1,5 +1,5 @@
 import { consume } from "@lit/context";
-import { initialState, Task, TaskStatus } from "@lit/task";
+import { initialState, Task } from "@lit/task";
 import { asNullableRecord as asConfigRecord } from "@openclaw/normalization-core/record-coerce";
 import { html, type PropertyValues } from "lit";
 import { property, state } from "lit/decorators.js";
@@ -13,11 +13,12 @@ import { renderDocsLink } from "../../components/settings-ui.ts";
 import { renderSettingsWorkspace } from "../../components/settings-workspace.ts";
 import { t } from "../../i18n/index.ts";
 import { normalizeAgentLabel } from "../../lib/agents/display.ts";
-import { createGatewayConnectionLifecycle } from "../../lib/gateway-connection-lifecycle.ts";
 import { isGatewayMethodAdvertised } from "../../lib/gateway-methods.ts";
 import { normalizeAgentId } from "../../lib/sessions/session-key.ts";
+import { GatewayPageController } from "../../lit/gateway-page-controller.ts";
 import { OpenClawLightDomElement } from "../../lit/openclaw-element.ts";
 import { SubscriptionsController } from "../../lit/subscriptions-controller.ts";
+import { UsageRefreshPolicy } from "../usage/refresh-policy.ts";
 import {
   modelProviderErrorMessage,
   runModelProviderConfigMutation,
@@ -44,57 +45,12 @@ import {
   buildProviderApiKeyPatch,
   DEFAULT_MODELS_REPLACE_PATHS,
 } from "./mutations.ts";
+import { isMissingMethodError, mergeProbeResults } from "./probe-results.ts";
+import type { ModelProvidersRouteData } from "./route.ts";
 import { renderModelProviders, type ModelProviderRowMessage } from "./view.ts";
 
 const MODEL_PROVIDERS_DOCS_URL = "https://docs.openclaw.ai/concepts/model-providers";
 
-export type ModelProvidersRouteData = {
-  data: ModelProvidersData;
-  /** Client the loader fetched from; null when it ran disconnected. */
-  client: GatewayBrowserClient | null;
-  /** Concrete agent whose credential store populated the auth snapshot. */
-  agentId: string | null;
-};
-
-function isMissingMethodError(error: unknown): boolean {
-  return /method (?:not found|not supported)|unknown method/iu.test(
-    modelProviderErrorMessage(error),
-  );
-}
-
-const PROBE_FAILURE_PRIORITY: readonly ModelsProbeResult["status"][] = [
-  "auth",
-  "billing",
-  "rate_limit",
-  "timeout",
-  "format",
-  "no_model",
-  "unknown",
-];
-
-function mergeProbeResults(cardId: string, results: ModelsProbeResult[]): ModelsProbeResult {
-  if (results.length === 1) {
-    return results[0]!;
-  }
-  const status = results.some((result) => result.status === "ok")
-    ? "ok"
-    : (PROBE_FAILURE_PRIORITY.find((candidate) =>
-        results.some((result) => result.status === candidate),
-      ) ?? "unknown");
-  const error = results.find((result) => result.status === status)?.error;
-  return {
-    provider: cardId,
-    status,
-    ...(error ? { error } : {}),
-    results: results.flatMap((result) =>
-      result.results.map((target) => ({
-        ...target,
-        label: `${result.provider}: ${target.label}`,
-      })),
-    ),
-  };
-}
-
 export class ModelProvidersPage extends OpenClawLightDomElement {
   @consume({ context: applicationContext, subscribe: true })
   private context!: ApplicationContext;
@@ -117,41 +73,61 @@ export class ModelProvidersPage extends OpenClawLightDomElement {
 
   /** Client the current data was loaded from; a new client means stale data. */
   private dataClient: GatewayBrowserClient | null = null;
-  private readonly connectionLifecycle = createGatewayConnectionLifecycle({
-    client: null,
-    phase: "stopped",
-  });
+  // Null Task runs supersede stale work without counting as a real load.
+  private loadClient: GatewayBrowserClient | null = null;
+  private routeDataObserved = false;
   // Global config writes survive agent switches; their card state does not.
   private agentEpoch = 0;
   private probeEpochs = new Map<string, number>();
   private readonly refreshTask = new Task(this, {
     autoRun: false,
-    args: () =>
-      [
-        this.context?.gateway.snapshot.phase === "connected"
-          ? (this.context.gateway.snapshot.client ?? null)
-          : null,
-        this.selectedAgentId,
-        false as boolean,
-      ] as const,
-    task: ([client, agentId, force], { signal }) =>
-      client && agentId
-        ? loadModelProvidersData(client, {
-            agentId,
-            ...(force ? { refresh: true } : {}),
-            signal,
-          }).then((data) => ({ client, data }))
-        : initialState,
+    task: (
+      [client, agentId, force]: [GatewayBrowserClient | null, string, boolean],
+      { signal },
+    ) => {
+      if (!client || !agentId) {
+        return initialState;
+      }
+      this.refreshPolicy.beginLoad();
+      return loadModelProvidersData(client, {
+        agentId,
+        ...(force ? { refresh: true } : {}),
+        signal,
+      }).then((data) => ({ client, data }));
+    },
     onComplete: ({ client, data }) => {
-      this.data = data;
-      this.dataClient = client;
+      this.loadClient = null;
+      this.adoptLoadedData(client, data);
+      this.refreshPolicy.flushPending();
+    },
+    onError: () => {
+      this.loadClient = null;
+      this.refreshPolicy.flushPending();
     },
   });
+  private readonly refreshPolicy = new UsageRefreshPolicy({
+    isLoading: () => this.loadClient !== null,
+    reload: () => void this.refresh({ force: false }),
+  });
+  private readonly gateway = new GatewayPageController(this, {
+    getGateway: () => this.context?.gateway,
+    onIdentityChange: () => this.resetConnectionState(),
+    invalidateRequests: () => this.invalidateRequests(),
+    ensureInitialData: () => this.ensureInitialData(),
+    onSnapshot: (change) => {
+      if (change.initial) {
+        this.resetConnectionState();
+      } else if (change.connectionChanged && !change.identityChanged) {
+        // Keep the last snapshot visible while the canonical reconnect load replaces it.
+        this.resetConnectionState({ preserveVisibleData: true });
+      }
+      if (change.becameConnected && !change.initial) {
+        this.refreshPolicy.request("reconnect");
+      }
+    },
+    onPageActivation: () => this.refreshPolicy.request("focus"),
+  });
   private readonly subscriptions = new SubscriptionsController(this)
-    .watch(
-      () => this.context?.gateway,
-      (gateway, notify) => gateway.subscribe(notify),
-    )
     .watch(
       () => this.context?.runtimeConfig,
       (runtimeConfig, notify) => runtimeConfig.subscribe(notify),
@@ -176,31 +152,30 @@ export class ModelProvidersPage extends OpenClawLightDomElement {
     );
 
   override disconnectedCallback() {
-    this.connectionLifecycle.transition({ client: null, phase: "stopped" });
-    void this.refreshTask.run([null, "", false]);
     this.subscriptions.clear();
     super.disconnectedCallback();
   }
 
   override willUpdate(changed: PropertyValues) {
-    if (changed.has("routeData") && this.routeData) {
+    if (changed.has("routeData") && this.routeData !== undefined) {
+      this.routeDataObserved = true;
       const selectedAgentId = this.resolveSelectedAgentId();
       this.setSelectedAgent(selectedAgentId);
-      if ((this.routeData.agentId ?? "") === selectedAgentId) {
-        this.data = this.routeData.data;
-        this.dataClient = this.routeData.client;
+      if (
+        (this.routeData.agentId ?? "") === selectedAgentId &&
+        this.gateway.isRouteDataCurrent(this.routeData)
+      ) {
+        this.adoptLoadedData(this.routeData.client, this.routeData.data);
       } else {
         this.data = null;
         this.dataClient = null;
+        this.refreshPolicy.resetPayload();
       }
+      this.ensureInitialData();
     }
   }
 
-  override updated() {
-    const snapshot = this.context.gateway.snapshot;
-    if (this.connectionLifecycle.transition(snapshot)) {
-      this.resetConnectionState(snapshot.client, snapshot.phase === "connected");
-    }
+  private ensureInitialData() {
     if (
       !this.context.agents.state.agentsList &&
       !this.context.agents.state.agentsLoading &&
@@ -208,21 +183,40 @@ export class ModelProvidersPage extends OpenClawLightDomElement {
     ) {
       void this.context.agents.ensureList();
     }
+    if (!this.routeDataObserved && this.routeData !== undefined) {
+      return;
+    }
+    const client = this.gateway.client;
     if (
-      snapshot.phase !== "connected" ||
-      !snapshot.client ||
-      this.refreshTask.status === TaskStatus.PENDING
+      !this.gateway.connected ||
+      !client ||
+      !this.selectedAgentId ||
+      this.loadClient !== null ||
+      (this.data !== null && this.data.updatedAt !== null && client === this.dataClient)
     ) {
       return;
     }
-    const stale = this.data === null || this.data.updatedAt === null;
-    if (stale || snapshot.client !== this.dataClient) {
-      void this.refresh({ force: false });
-    }
+    void this.refresh({ force: false });
   }
 
-  private resetConnectionState(client: GatewayBrowserClient | null, connected: boolean) {
+  private adoptLoadedData(client: GatewayBrowserClient | null, data: ModelProvidersData) {
+    this.data = data;
+    this.dataClient = client;
+    this.refreshPolicy.setLastLoadedAtMs(data.providerUsage?.ok ? data.updatedAt : null);
+  }
+
+  private invalidateRequests() {
+    this.refreshPolicy.interrupt();
+    this.loadClient = null;
     void this.refreshTask.run([null, this.selectedAgentId, false]);
+  }
+
+  private resetConnectionState(options: { preserveVisibleData?: boolean } = {}) {
+    if (!options.preserveVisibleData) {
+      this.data = null;
+      this.dataClient = null;
+    }
+    this.refreshPolicy.resetPayload();
     this.busy = {};
     this.messages = {};
     this.probeResults = {};
@@ -235,13 +229,10 @@ export class ModelProvidersPage extends OpenClawLightDomElement {
     this.addProviderId = "";
     this.addProviderKey = "";
     this.defaultsDraft = null;
-    if (!connected || client !== this.dataClient) {
-      this.data = null;
-    }
   }
 
   private isCurrentClient(client: GatewayBrowserClient, epoch: number): boolean {
-    return this.connectionLifecycle.isCurrent({ client, epoch });
+    return this.gateway.isCurrent({ client, epoch });
   }
 
   private resolveSelectedAgentId(): string {
@@ -267,19 +258,27 @@ export class ModelProvidersPage extends OpenClawLightDomElement {
     if (!this.setSelectedAgent(agentId)) {
       return;
     }
-    void this.refreshTask.run([null, agentId, false]);
+    this.invalidateRequests();
     this.data = null;
+    this.dataClient = null;
+    this.refreshPolicy.resetPayload();
     // probeEpochs stays: per-card counters must remain monotonic across agent
     // switches, or an in-flight probe from the old agent can reuse an epoch
     // and clobber a newer probe's state (A->B->A ABA race).
     this.requestUpdate();
+    this.ensureInitialData();
   }
 
   private refresh(opts: { force: boolean }): Promise<void> {
-    const client = this.context.gateway.snapshot.client;
-    if (!client || !this.selectedAgentId) {
+    if (!this.selectedAgentId) {
       return Promise.resolve();
     }
+    const client = this.gateway.client;
+    if (!this.gateway.connected || !client) {
+      this.refreshPolicy.markLoadDeferred();
+      return Promise.resolve();
+    }
+    this.loadClient = client;
     return this.refreshTask.run([client, this.selectedAgentId, opts.force]);
   }
 
@@ -351,7 +350,7 @@ export class ModelProvidersPage extends OpenClawLightDomElement {
     if (!client) {
       return { ok: false };
     }
-    const clientEpoch = this.connectionLifecycle.epoch;
+    const clientEpoch = this.gateway.epoch;
     const agentEpoch = this.agentEpoch;
     return runModelProviderConfigMutation(
       {
@@ -434,7 +433,7 @@ export class ModelProvidersPage extends OpenClawLightDomElement {
     if (!client || !this.canMutate() || this.busy[key] || this.probeUnsupported) {
       return;
     }
-    const clientEpoch = this.connectionLifecycle.epoch;
+    const clientEpoch = this.gateway.epoch;
     const agentId = this.selectedAgentId;
     const agentEpoch = this.agentEpoch;
     const probeEpoch = (this.probeEpochs.get(cardId) ?? 0) + 1;
@@ -488,7 +487,7 @@ export class ModelProvidersPage extends OpenClawLightDomElement {
     if (!client || !this.canMutate() || this.busy[key]) {
       return;
     }
-    const clientEpoch = this.connectionLifecycle.epoch;
+    const clientEpoch = this.gateway.epoch;
     const agentId = this.selectedAgentId;
     const agentEpoch = this.agentEpoch;
     this.clearProbe(cardId);
@@ -625,7 +624,7 @@ export class ModelProvidersPage extends OpenClawLightDomElement {
     const body = renderModelProviders({
       connected: gatewaySnapshot.phase === "connected",
       loading: gatewaySnapshot.phase === "connected" && this.data === null && !rosterError,
-      refreshing: this.refreshTask.status === TaskStatus.PENDING,
+      refreshing: this.loadClient !== null,
       error: rosterError ?? data.error ?? data.catalogError,
       providerUsageFailed: data.providerUsage?.ok === false,
       updatedAt: data.updatedAt,
diff --git a/ui/src/pages/model-providers/probe-results.ts b/ui/src/pages/model-providers/probe-results.ts
new file mode 100644
index 000000000000..897f0f25c255
--- /dev/null
+++ b/ui/src/pages/model-providers/probe-results.ts
@@ -0,0 +1,41 @@
+import type { ModelsProbeResult } from "../../api/types.ts";
+import { modelProviderErrorMessage } from "./config-mutation.ts";
+
+const PROBE_FAILURE_PRIORITY: readonly ModelsProbeResult["status"][] = [
+  "auth",
+  "billing",
+  "rate_limit",
+  "timeout",
+  "format",
+  "no_model",
+  "unknown",
+];
+
+export function isMissingMethodError(error: unknown): boolean {
+  return /method (?:not found|not supported)|unknown method/iu.test(
+    modelProviderErrorMessage(error),
+  );
+}
+
+export function mergeProbeResults(cardId: string, results: ModelsProbeResult[]): ModelsProbeResult {
+  if (results.length === 1) {
+    return results[0]!;
+  }
+  const status = results.some((result) => result.status === "ok")
+    ? "ok"
+    : (PROBE_FAILURE_PRIORITY.find((candidate) =>
+        results.some((result) => result.status === candidate),
+      ) ?? "unknown");
+  const error = results.find((result) => result.status === status)?.error;
+  return {
+    provider: cardId,
+    status,
+    ...(error ? { error } : {}),
+    results: results.flatMap((result) =>
+      result.results.map((target) => ({
+        ...target,
+        label: `${result.provider}: ${target.label}`,
+      })),
+    ),
+  };
+}
diff --git a/ui/src/pages/model-providers/route.ts b/ui/src/pages/model-providers/route.ts
index 39ee83b71537..8b26d1676b8d 100644
--- a/ui/src/pages/model-providers/route.ts
+++ b/ui/src/pages/model-providers/route.ts
@@ -3,12 +3,25 @@ import { html } from "lit";
 import { routePageSpec } from "../../app-route-paths.ts";
 import type { ApplicationContext } from "../../app/context.ts";
 import { normalizeAgentId } from "../../lib/sessions/session-key.ts";
-import type { ModelProvidersRouteData } from "./model-providers-page.ts";
+import type { ModelProvidersData } from "./load.ts";
+
+export type ModelProvidersRouteData = {
+  /** Gateway source that owned the route preload. */
+  gateway: ApplicationContext["gateway"];
+  /** Exact Gateway snapshot captured before the preload began. */
+  gatewaySnapshot: ApplicationContext["gateway"]["snapshot"];
+  data: ModelProvidersData;
+  /** Client the loader fetched from; null when it ran disconnected. */
+  client: ApplicationContext["gateway"]["snapshot"]["client"];
+  /** Concrete agent whose credential store populated the auth snapshot. */
+  agentId: string | null;
+};
 
 async function loadModelProvidersRouteData(
   context: ApplicationContext,
 ): Promise<ModelProvidersRouteData> {
-  const gatewaySnapshot = context.gateway.snapshot;
+  const gateway = context.gateway;
+  const gatewaySnapshot = gateway.snapshot;
   const { EMPTY_MODEL_PROVIDERS_DATA, loadModelProvidersData } = await import("./load.ts");
   const client = gatewaySnapshot.phase === "connected" ? gatewaySnapshot.client : null;
   if (!context.agentSelection.state.selectedId && client) {
@@ -17,9 +30,15 @@ async function loadModelProvidersRouteData(
   const selectedAgentId = context.agentSelection.state.selectedId;
   const agentId = selectedAgentId ? normalizeAgentId(selectedAgentId) : null;
   if (!client || !agentId) {
-    return { data: EMPTY_MODEL_PROVIDERS_DATA, client: null, agentId };
+    return { gateway, gatewaySnapshot, data: EMPTY_MODEL_PROVIDERS_DATA, client: null, agentId };
   }
-  return { data: await loadModelProvidersData(client, { agentId }), client, agentId };
+  return {
+    gateway,
+    gatewaySnapshot,
+    data: await loadModelProvidersData(client, { agentId }),
+    client,
+    agentId,
+  };
 }
 
 export const page = definePage({
diff --git a/ui/src/pages/route-provenance.test.ts b/ui/src/pages/route-provenance.test.ts
index 2ea824847a14..d8e0564034d5 100644
--- a/ui/src/pages/route-provenance.test.ts
+++ b/ui/src/pages/route-provenance.test.ts
@@ -6,8 +6,10 @@ import type { ApplicationContext, ApplicationGatewaySnapshot } from "../app/cont
 import { page as agentsPage, type AgentsRouteData } from "./agents/route.ts";
 import type { DevicesRouteData } from "./devices/devices-page.ts";
 import { page as devicesPage } from "./devices/route.ts";
-import type { ModelProvidersRouteData } from "./model-providers/model-providers-page.ts";
-import { page as modelProvidersPage } from "./model-providers/route.ts";
+import {
+  page as modelProvidersPage,
+  type ModelProvidersRouteData,
+} from "./model-providers/route.ts";
 import type { PluginsRouteData } from "./plugins/plugins-page.ts";
 import { page as pluginsPage } from "./plugins/route.ts";
 import { page as sessionsPage, type SessionsRouteData } from "./sessions/route.ts";
@@ -148,7 +150,8 @@ describe("route preload gateway provenance", () => {
     const replacementClient = {
       request: replacementRequest,
     } as unknown as GatewayBrowserClient;
-    const mutable = mutableGateway(snapshot(originalClient, true));
+    const originalSnapshot = snapshot(originalClient, true);
+    const mutable = mutableGateway(originalSnapshot);
     const request = loadRoute<ModelProvidersRouteData>(modelProvidersPage, {
       gateway: mutable.gateway,
       agents: {
@@ -166,6 +169,8 @@ describe("route preload gateway provenance", () => {
     mutable.replaceSnapshot(snapshot(replacementClient, true));
     const data = await request;
 
+    expect(data.gateway).toBe(mutable.gateway);
+    expect(data.gatewaySnapshot).toBe(originalSnapshot);
     expect(data.client).toBe(originalClient);
     expect(originalRequest).toHaveBeenCalled();
     expect(replacementRequest).not.toHaveBeenCalled();
diff --git a/ui/src/pages/usage/refresh-policy.ts b/ui/src/pages/usage/refresh-policy.ts
index c44fc143ad28..436f76bd85fe 100644
--- a/ui/src/pages/usage/refresh-policy.ts
+++ b/ui/src/pages/usage/refresh-policy.ts
@@ -46,10 +46,6 @@ export class UsageRefreshPolicy {
     this.lastLoadedAtMs = value;
   }
 
-  markLoaded(): void {
-    this.lastLoadedAtMs = Date.now();
-  }
-
   resetPayload(): void {
     this.lastLoadedAtMs = null;
     this.reloadPending = false;
diff --git a/ui/src/pages/usage/usage-page.test.ts b/ui/src/pages/usage/usage-page.test.ts
index 4050532f4291..288ed2d7c95d 100644
--- a/ui/src/pages/usage/usage-page.test.ts
+++ b/ui/src/pages/usage/usage-page.test.ts
@@ -82,6 +82,69 @@ afterEach(() => {
 });
 
 describe("UsagePage provider usage outcome", () => {
+  it.each(["direct", "preload"] as const)(
+    "retries a failed %s provider usage result on the next page activation",
+    async (loadSource) => {
+      vi.spyOn(document, "hasFocus").mockReturnValue(true);
+      vi.spyOn(document, "visibilityState", "get").mockReturnValue("visible");
+      let providerUnavailable = loadSource === "direct";
+      const request = vi.fn(async (method: string): Promise<unknown> => {
+        if (method === "usage.status") {
+          if (providerUnavailable) {
+            throw new Error("provider usage unreachable");
+          }
+          return { updatedAt: 2, providers: [] };
+        }
+        return method === "usage.cost" ? { daily: [] } : { sessions: [], totals: null };
+      });
+      const page = document.createElement("openclaw-usage-page") as TestUsagePage;
+      page.context = contextWithClient({ request } as unknown as GatewayBrowserClient);
+      page.render = () => nothing;
+      document.body.append(page);
+      await page.updateComplete;
+      page.routeData = {
+        gateway: page.context.gateway,
+        gatewaySnapshot: page.context.gateway.snapshot,
+        query: {
+          startDate: "2026-08-07",
+          endDate: "2026-08-07",
+          scope: "family",
+          timeZone: "local",
+          agentId: null,
+        },
+        result: null,
+        costSummary: null,
+        providerUsage:
+          loadSource === "preload" ? { ok: false, error: { kind: "request-failed" } } : null,
+        loadedAtMs: loadSource === "preload" ? Date.now() : null,
+        error: null,
+      };
+      await page.updateComplete;
+      if (loadSource === "direct") {
+        (page as unknown as { refreshPolicy: { reload: () => void } }).refreshPolicy.reload();
+        await vi.waitFor(() => expect(page.providerUsage).toMatchObject({ ok: false }));
+      }
+      const previousCalls = request.mock.calls.filter(
+        ([method]) => method === "usage.status",
+      ).length;
+      providerUnavailable = false;
+
+      window.dispatchEvent(new Event("focus"));
+
+      await vi.waitFor(() => {
+        expect(request.mock.calls.filter(([method]) => method === "usage.status")).toHaveLength(
+          previousCalls + 1,
+        );
+      });
+      await vi.waitFor(() =>
+        expect(page.providerUsage).toEqual({
+          ok: true,
+          value: { updatedAt: 2, providers: [] },
+        }),
+      );
+    },
+  );
+
   it("keeps the last successful provider usage data when a later aggregate load fails", async () => {
     let phase = 1;
     const summary = { updatedAt: 1, providers: [{ provider: "openai", windows: [] }] };
diff --git a/ui/src/pages/usage/usage-page.ts b/ui/src/pages/usage/usage-page.ts
index 2fe1e7666873..381cbc7c42f3 100644
--- a/ui/src/pages/usage/usage-page.ts
+++ b/ui/src/pages/usage/usage-page.ts
@@ -191,7 +191,7 @@ class UsagePage extends OpenClawLightDomElement {
       this.usageCostSummary = value.costSummary;
       this.providerUsage = value.providerUsage;
       this.usageError = null;
-      this.refreshPolicy.markLoaded();
+      this.refreshPolicy.setLastLoadedAtMs(value.providerUsage.ok ? Date.now() : null);
       this.refreshPolicy.flushPending();
     },
     onError: (error) => {
@@ -315,7 +315,7 @@ class UsagePage extends OpenClawLightDomElement {
     this.usageResult = data.result;
     this.usageCostSummary = data.costSummary;
     this.providerUsage = data.providerUsage;
-    this.refreshPolicy.setLastLoadedAtMs(data.loadedAtMs);
+    this.refreshPolicy.setLastLoadedAtMs(data.providerUsage?.ok ? data.loadedAtMs : null);
     this.usageError = data.error;
   }
 

From eb502d9aef286d86f8f42869f871835ec66cb83d Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 12:00:58 -0700
Subject: [PATCH 070/124] fix(claws): remove exec approvals when a Claw agent
 is removed (#127365)

`claws remove` deleted the agent and reported status complete while its
exec-approvals policy survived in the shared state DB, so a later agent
reusing the id silently inherited the old allowlist.

claws was the third agent-removal path and the only one that never opened
an agent-deletion journal, which withAgentExecApprovalsRemoved requires as
its fence. Open the journal around the config commit and run both commit
branches inside the approvals fence, matching the gateway and CLI paths.

Cron stays declaration-owned and unchanged.
---
 src/claws/lifecycle-config-removal.ts        |  82 +++++++---
 src/claws/lifecycle-remove-approvals.test.ts | 156 +++++++++++++++++++
 2 files changed, 214 insertions(+), 24 deletions(-)
 create mode 100644 src/claws/lifecycle-remove-approvals.test.ts

diff --git a/src/claws/lifecycle-config-removal.ts b/src/claws/lifecycle-config-removal.ts
index a7e4cc83c51f..eceb3989944c 100644
--- a/src/claws/lifecycle-config-removal.ts
+++ b/src/claws/lifecycle-config-removal.ts
@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { stableStringify } from "@openclaw/normalization-core";
+import { beginAgentDeletion } from "../agents/agent-lifecycle-registry.js";
 import { listAgentEntries } from "../agents/agent-scope.js";
 import { getRuntimeConfig } from "../config/config.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
@@ -7,7 +8,9 @@ import {
   AgentConfigPreconditionError,
   deleteAgentConfigEntry,
 } from "../gateway/server-methods/agents-config-mutations.js";
+import { withAgentExecApprovalsRemoved } from "../infra/exec-approvals.js";
 import { normalizeAgentId } from "../routing/session-key.js";
+import { readAgentDeletionJournal } from "../state/agent-deletion-journal.js";
 import { digestClawAgentConfig } from "./agent-config-digest.js";
 import {
   deletionEffects,
@@ -17,6 +20,25 @@ import {
 
 export type ConfigCommit = (transform: (config: OpenClawConfig) => OpenClawConfig) => Promise<void>;
 
+type ClawAgentConfigRemovalParams = {
+  agentId: string;
+  expectedDigest: string;
+  expectedRemovalSurfaceDigest: string;
+  expectedState: "present" | "missing";
+  fallbackWorkspace: string;
+  config?: OpenClawConfig;
+  commitConfig?: ConfigCommit;
+  trashPath?: ClawTrashPath;
+  onModified: () => Error;
+};
+
+type ClawAgentConfigRemovalResult = {
+  agentRemoved: boolean;
+  cleanupTargets?: ClawCleanupTargets;
+  configBeforeDelete: OpenClawConfig;
+  nextConfig: OpenClawConfig;
+};
+
 export { digestClawAgentConfig } from "./agent-config-digest.js";
 
 export function digestClawAgentRemovalSurface(config: OpenClawConfig, agentId: string): string {
@@ -32,31 +54,11 @@ export function digestClawAgentRemovalSurface(config: OpenClawConfig, agentId: s
   return `sha256:${createHash("sha256").update(stableStringify(surface)).digest("hex")}`;
 }
 
-export async function claimClawAgentConfigRemoval(params: {
-  agentId: string;
-  expectedDigest: string;
-  expectedRemovalSurfaceDigest: string;
-  expectedState: "present" | "missing";
-  fallbackWorkspace: string;
-  config?: OpenClawConfig;
-  commitConfig?: ConfigCommit;
-  trashPath?: ClawTrashPath;
-  onModified: () => Error;
-}): Promise<{
-  agentRemoved: boolean;
-  cleanupTargets?: ClawCleanupTargets;
-  configBeforeDelete: OpenClawConfig;
-  nextConfig: OpenClawConfig;
-}> {
+async function commitClawAgentConfigRemoval(
+  params: ClawAgentConfigRemovalParams,
+): Promise<ClawAgentConfigRemovalResult> {
   if (params.commitConfig) {
-    let result:
-      | {
-          agentRemoved: boolean;
-          cleanupTargets?: ClawCleanupTargets;
-          configBeforeDelete: OpenClawConfig;
-          nextConfig: OpenClawConfig;
-        }
-      | undefined;
+    let result: ClawAgentConfigRemovalResult | undefined;
     await params.commitConfig((config) => {
       const effects = deletionEffects(config, params.agentId, params.fallbackWorkspace);
       const agent = listAgentEntries(config).find((candidate) => candidate.id === params.agentId);
@@ -149,3 +151,35 @@ export async function claimClawAgentConfigRemoval(params: {
     };
   }
 }
+
+export async function claimClawAgentConfigRemoval(params: ClawAgentConfigRemovalParams) {
+  const config = params.config ?? getRuntimeConfig();
+  const effects = deletionEffects(config, params.agentId, params.fallbackWorkspace);
+  // beginAgentDeletion takes over an existing journal row instead of refusing it, so rolling back
+  // a row this call did not open would erase another deletion's record.
+  const existingJournal = readAgentDeletionJournal(params.agentId);
+  const deletion = beginAgentDeletion({
+    agentId: params.agentId,
+    workspaceDir: effects.workspace,
+    agentDir: effects.agentDir,
+    sessionsDir: effects.sessionsDir,
+    // Claw removal owns selective cleanup and may retain modified or untracked workspace entries,
+    // so the journal must not claim authority to trash them.
+    deleteFiles: existingJournal?.deleteFiles ?? false,
+  });
+  try {
+    const result = await withAgentExecApprovalsRemoved(params.agentId, async () =>
+      commitClawAgentConfigRemoval({ ...params, config }),
+    );
+    deletion.commit();
+    // The journal fences only the roster and approvals commit here; Claw's own filesystem cleanup
+    // runs afterwards and may legitimately end partial, so completion is recorded now.
+    deletion.finish();
+    return result;
+  } catch (error) {
+    if (!existingJournal) {
+      deletion.rollback();
+    }
+    throw error;
+  }
+}
diff --git a/src/claws/lifecycle-remove-approvals.test.ts b/src/claws/lifecycle-remove-approvals.test.ts
new file mode 100644
index 000000000000..52d3d9c9b440
--- /dev/null
+++ b/src/claws/lifecycle-remove-approvals.test.ts
@@ -0,0 +1,156 @@
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { useAutoCleanupTempDirTracker } from "../../test/helpers/temp-dir.js";
+import { beginAgentDeletion } from "../agents/agent-lifecycle-registry.js";
+import { withTempHomeConfig, writeOpenClawConfig } from "../config/test-helpers.js";
+import type { OpenClawConfig } from "../config/types.openclaw.js";
+import { loadExecApprovals, saveExecApprovals } from "../infra/exec-approvals.js";
+import { readAgentDeletionJournal } from "../state/agent-deletion-journal.js";
+import { closeOpenClawStateDatabaseForTest } from "../state/openclaw-state-db.js";
+import { captureEnv, setTestEnvValue } from "../test-utils/env.js";
+import { applyClawAddPlan } from "./add.js";
+import {
+  claimClawAgentConfigRemoval,
+  digestClawAgentRemovalSurface,
+} from "./lifecycle-config-removal.js";
+import { applyClawRemovePlan, buildClawRemovePlan } from "./lifecycle-state.js";
+import { buildClawAddPlan } from "./lifecycle.js";
+import { parseClawManifest } from "./schema.js";
+import type { ClawSourceIdentity } from "./types.js";
+
+const tempDirs = useAutoCleanupTempDirTracker(afterEach);
+const envSnapshot = captureEnv(["OPENCLAW_STATE_DIR"]);
+
+afterEach(() => {
+  closeOpenClawStateDatabaseForTest();
+  envSnapshot.restore();
+});
+
+async function buildApprovalFixture() {
+  const root = tempDirs.make("openclaw-claw-remove-approvals-");
+  const parsed = parseClawManifest({
+    schemaVersion: 1,
+    agent: { id: "worker", name: "Worker" },
+  });
+  if (!parsed.ok) {
+    throw new Error(JSON.stringify(parsed.diagnostics));
+  }
+  const source: ClawSourceIdentity = {
+    kind: "package",
+    name: "@acme/worker",
+    version: "1.0.0",
+    packageRoot: root,
+    manifestPath: join(root, "openclaw.claw.json"),
+    integrityKind: "artifact",
+    integrity: "sha256:manifest",
+    byteLength: 100,
+  };
+  return await buildClawAddPlan({
+    manifest: parsed.manifest,
+    source,
+    context: { workspace: join(root, "workspace-worker") },
+  });
+}
+
+describe("Claw exec approvals removal", () => {
+  it.each([
+    { label: "config-file commit", useCommitConfig: false },
+    { label: "commitConfig seam", useCommitConfig: true },
+  ])("removes only the claw agent policy through the $label", async ({ useCommitConfig }) => {
+    const addPlan = await buildApprovalFixture();
+
+    await withTempHomeConfig({}, async ({ home }) => {
+      const env = { OPENCLAW_STATE_DIR: join(home, ".openclaw") };
+      setTestEnvValue("OPENCLAW_STATE_DIR", env.OPENCLAW_STATE_DIR);
+      let config: OpenClawConfig = {};
+      await applyClawAddPlan(addPlan, {
+        consentPlanIntegrity: addPlan.planIntegrity,
+        env,
+        commitConfig: async (transform) => {
+          config = transform(config);
+        },
+      });
+      await writeOpenClawConfig(home, config);
+      saveExecApprovals({
+        version: 1,
+        agents: {
+          "*": { security: "deny" },
+          worker: {
+            security: "allowlist",
+            allowlist: [{ pattern: "/usr/bin/rm" }],
+          },
+          kept: {
+            security: "allowlist",
+            allowlist: [{ pattern: "/usr/bin/keep" }],
+          },
+        },
+      });
+      const plan = useCommitConfig
+        ? await buildClawRemovePlan("worker", { env, config })
+        : await buildClawRemovePlan("worker");
+      const common = {
+        consentPlanIntegrity: plan.planIntegrity,
+        trashPath: async () => true,
+      };
+
+      const result = useCommitConfig
+        ? await applyClawRemovePlan(plan, {
+            ...common,
+            env,
+            config,
+            commitConfig: async (transform) => {
+              config = transform(config);
+            },
+          })
+        : await applyClawRemovePlan(plan, common);
+
+      expect(result).toMatchObject({ status: "complete", agentRemoved: true });
+      expect(loadExecApprovals().agents).toEqual({
+        "*": { security: "deny" },
+        kept: {
+          security: "allowlist",
+          allowlist: [expect.objectContaining({ pattern: "/usr/bin/keep" })],
+        },
+      });
+      expect(readAgentDeletionJournal("worker")).toMatchObject({
+        cleanupCompleted: true,
+        deleteFiles: false,
+      });
+    });
+  });
+
+  // beginAgentDeletion takes over an existing journal row, so a failed Claw removal must not roll
+  // back a deletion another path started.
+  it.each([
+    { label: "keeps a pre-existing journal", seedJournal: true },
+    { label: "rolls back the journal it opened", seedJournal: false },
+  ])("$label when the config commit fails", async ({ seedJournal }) => {
+    const root = tempDirs.make("openclaw-claw-remove-journal-");
+    setTestEnvValue("OPENCLAW_STATE_DIR", join(root, "state"));
+    if (seedJournal) {
+      beginAgentDeletion({
+        agentId: "worker",
+        agentDir: join(root, "agent"),
+        workspaceDir: join(root, "workspace"),
+        sessionsDir: join(root, "sessions"),
+      });
+    }
+
+    await expect(
+      claimClawAgentConfigRemoval({
+        agentId: "worker",
+        expectedDigest: "sha256:unused",
+        expectedRemovalSurfaceDigest: digestClawAgentRemovalSurface({}, "worker"),
+        expectedState: "present",
+        fallbackWorkspace: join(root, "workspace"),
+        config: {},
+        commitConfig: async () => {
+          throw new Error("claw commit failed");
+        },
+        onModified: () => new Error("claw agent modified"),
+      }),
+    ).rejects.toThrow("claw commit failed");
+
+    expect(readAgentDeletionJournal("worker") === undefined).toBe(!seedJournal);
+  });
+});

From 9de2b230e968cb1e2a211a60be8f65a0e0da1c95 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 12:02:20 -0700
Subject: [PATCH 071/124] fix(agents): stop canceled subagents reporting
 timeouts (#125407)

* fix(agents): preserve cancelled subagent outcomes

* fix(agents): preserve provisional cancellation precedence

* fix(agents): scope cancellation precedence to subagents

* fix(agents): preserve provider timeout precedence

---------

Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
---
 .../announce/subagent-announce-output.ts      |   8 +-
 .../registry/subagent-registry-listener.ts    | 113 ++++++++----------
 .../subagent-registry-pending-lifecycle.ts    |  44 ++++---
 .../registry/subagent-registry-run-wait.ts    |   8 +-
 ...registry.lifecycle-retry-grace.e2e.test.ts |  70 +++++++++--
 ...bagent-registry.persistence.resume.test.ts |  26 ++--
 .../subagent-terminal-outcome.test.ts         |  26 ++++
 .../subagents/subagent-terminal-outcome.ts    |  13 ++
 8 files changed, 194 insertions(+), 114 deletions(-)
 create mode 100644 src/agents/subagents/subagent-terminal-outcome.test.ts
 create mode 100644 src/agents/subagents/subagent-terminal-outcome.ts

diff --git a/src/agents/subagents/announce/subagent-announce-output.ts b/src/agents/subagents/announce/subagent-announce-output.ts
index 382df235ad7f..ded441a5043a 100644
--- a/src/agents/subagents/announce/subagent-announce-output.ts
+++ b/src/agents/subagents/announce/subagent-announce-output.ts
@@ -10,10 +10,7 @@ import type { SessionTranscriptRuntimeTarget } from "../../../config/sessions/se
 import { resolveFreshSessionTotalTokens } from "../../../config/sessions/types.js";
 import { isFastTestRuntimeEnv } from "../../../infra/env.js";
 import { formatDurationCompact } from "../../../infra/format-time/format-duration.js";
-import {
-  buildAgentRunTerminalOutcomeFromWaitResult,
-  classifyAgentRunTerminalOutcome,
-} from "../../agent-run-terminal-outcome.js";
+import { buildAgentRunTerminalOutcomeFromWaitResult } from "../../agent-run-terminal-outcome.js";
 import { wrapPromptDataBlock } from "../../sanitize-for-prompt.js";
 import { extractStoredAssistantText, sanitizeTextContent } from "../../tools/chat-history-text.js";
 import {
@@ -21,6 +18,7 @@ import {
   selectDeliverableSessionsReply,
 } from "../../tools/sessions-send-tokens.js";
 import { compareSubagentRunGeneration } from "../registry/subagent-run-generation.js";
+import { classifySubagentTerminalOutcome } from "../subagent-terminal-outcome.js";
 import {
   captureSubagentCompletionReplyUsing,
   readLatestSubagentOutputWithRetryUsing,
@@ -356,7 +354,7 @@ export function applySubagentWaitOutcome(params: {
   // primary normalizers, so apply the canonical classification here instead
   // of re-enumerating reason groups.
   if (terminalOutcome) {
-    switch (classifyAgentRunTerminalOutcome(terminalOutcome)) {
+    switch (classifySubagentTerminalOutcome(terminalOutcome)) {
       case "timeout":
         outcome = { status: "timeout" };
         break;
diff --git a/src/agents/subagents/registry/subagent-registry-listener.ts b/src/agents/subagents/registry/subagent-registry-listener.ts
index 84880a0e2523..c12f5fe0cf2b 100644
--- a/src/agents/subagents/registry/subagent-registry-listener.ts
+++ b/src/agents/subagents/registry/subagent-registry-listener.ts
@@ -1,13 +1,8 @@
 import type { AgentEventPayload } from "../../../infra/agent-events.js";
 import { runWithGatewayIndependentRootWorkAdmission } from "../../../process/gateway-work-admission.js";
-import {
-  formatAbandonedLivenessError,
-  formatBlockedLivenessError,
-  isAbandonedLivenessState,
-  isBlockedLivenessState,
-} from "../../../shared/agent-liveness.js";
+import { buildAgentRunTerminalOutcomeFromLifecycleEvent } from "../../agent-run-terminal-outcome.js";
 import { normalizeAgentRunTerminalReplySnapshot } from "../../agent-run-terminal-reply.js";
-import { isAbortedAgentStopReason } from "../../run-termination.js";
+import { classifySubagentTerminalOutcome } from "../subagent-terminal-outcome.js";
 import {
   SUBAGENT_ENDED_REASON_COMPLETE,
   SUBAGENT_ENDED_REASON_ERROR,
@@ -82,11 +77,6 @@ export function createSubagentRegistryListener(config: {
         }
         const endedAt = typeof evt.data?.endedAt === "number" ? evt.data.endedAt : Date.now();
         const startedAt = typeof evt.data?.startedAt === "number" ? evt.data.startedAt : undefined;
-        const error = typeof evt.data?.error === "string" ? evt.data.error : undefined;
-        const livenessState =
-          typeof evt.data?.livenessState === "string" ? evt.data.livenessState : undefined;
-        const stopReason =
-          typeof evt.data?.stopReason === "string" ? evt.data.stopReason : undefined;
         const terminalReply = normalizeAgentRunTerminalReplySnapshot(evt.data?.terminalReply);
         // sessions_yield ends the turn by aborting the run signal, so a yielded
         // terminal can also look aborted. An explicit yield is authoritative — pause,
@@ -106,64 +96,29 @@ export function createSubagentRegistryListener(config: {
           }
           return;
         }
-        if (isAbortedAgentStopReason(stopReason)) {
-          pendingLifecycle.clear(evt.runId);
-          await completeSubagentRunWithRecovery(
-            {
-              runId: evt.runId,
-              endedAt,
-              outcome: {
-                status: "error",
-                error: "subagent run terminated",
-              },
-              reason: SUBAGENT_ENDED_REASON_KILLED,
-              sendFarewell: true,
-              accountId: entry.requesterOrigin?.accountId,
-              triggerCleanup: true,
-              startedAt,
-              terminalReply,
-            },
-            "lifecycle-killed-event",
-          );
-          return;
-        }
-        if (phase === "error") {
-          pendingLifecycle.scheduleError({
+        const terminalOutcome = buildAgentRunTerminalOutcomeFromLifecycleEvent({
+          phase,
+          data: evt.data,
+          startedAt,
+          endedAt,
+        });
+        const classification = classifySubagentTerminalOutcome(terminalOutcome);
+        if (
+          classification === "cancellation" &&
+          evt.data?.aborted === true &&
+          evt.data.stopReason === undefined &&
+          evt.data.status === undefined &&
+          evt.data.timeoutPhase === undefined
+        ) {
+          pendingLifecycle.scheduleCancellation({
             runId: evt.runId,
             endedAt,
             startedAt,
             terminalReply,
-            error,
           });
           return;
         }
-        const blocked = isBlockedLivenessState(livenessState);
-        const abandoned = isAbandonedLivenessState(livenessState);
-        if (blocked || abandoned) {
-          pendingLifecycle.clear(evt.runId);
-          const blockedParams = {
-            runId: evt.runId,
-            endedAt,
-            outcome: {
-              status: "error" as const,
-              error: blocked
-                ? formatBlockedLivenessError(error)
-                : formatAbandonedLivenessError(error),
-            },
-            reason: SUBAGENT_ENDED_REASON_ERROR,
-            sendFarewell: true,
-            accountId: entry.requesterOrigin?.accountId,
-            triggerCleanup: true,
-            startedAt,
-            terminalReply,
-          };
-          await completeSubagentRunWithRecovery(
-            blockedParams,
-            blocked ? "lifecycle-blocked-event" : "lifecycle-abandoned-event",
-          );
-          return;
-        }
-        if (evt.data?.aborted) {
+        if (classification === "timeout") {
           pendingLifecycle.scheduleTimeout({
             runId: evt.runId,
             endedAt,
@@ -172,6 +127,38 @@ export function createSubagentRegistryListener(config: {
           });
           return;
         }
+        if (phase === "error" && classification === "failure") {
+          pendingLifecycle.scheduleError({
+            runId: evt.runId,
+            endedAt,
+            startedAt,
+            terminalReply,
+            error: terminalOutcome.error,
+          });
+          return;
+        }
+        if (classification !== "success") {
+          const cancelled = classification === "cancellation";
+          pendingLifecycle.clear(evt.runId);
+          await completeSubagentRunWithRecovery(
+            {
+              runId: evt.runId,
+              endedAt,
+              outcome: {
+                status: "error" as const,
+                error: cancelled ? "subagent run terminated" : terminalOutcome.error,
+              },
+              reason: cancelled ? SUBAGENT_ENDED_REASON_KILLED : SUBAGENT_ENDED_REASON_ERROR,
+              sendFarewell: true,
+              accountId: entry.requesterOrigin?.accountId,
+              triggerCleanup: true,
+              startedAt,
+              terminalReply,
+            },
+            cancelled ? "lifecycle-killed-event" : `lifecycle-${terminalOutcome.reason}-event`,
+          );
+          return;
+        }
         pendingLifecycle.clear(evt.runId);
         const completionParams = {
           runId: evt.runId,
diff --git a/src/agents/subagents/registry/subagent-registry-pending-lifecycle.ts b/src/agents/subagents/registry/subagent-registry-pending-lifecycle.ts
index a75c6e08298f..6d9658f964be 100644
--- a/src/agents/subagents/registry/subagent-registry-pending-lifecycle.ts
+++ b/src/agents/subagents/registry/subagent-registry-pending-lifecycle.ts
@@ -1,23 +1,29 @@
+import { AGENT_RUN_TERMINAL_RETRY_GRACE_MS } from "../../agent-run-terminal-outcome.js";
 import {
   SUBAGENT_ENDED_REASON_COMPLETE,
   SUBAGENT_ENDED_REASON_ERROR,
+  SUBAGENT_ENDED_REASON_KILLED,
 } from "./subagent-lifecycle-events.js";
 import type { SubagentCompletionRequest, SubagentRunRecord } from "./subagent-registry.types.js";
 
-const LIFECYCLE_RETRY_GRACE_MS = 15_000;
 const PENDING_LIFECYCLE_TERMINAL_TTL_MS = 5 * 60_000;
 
 type PendingLifecycleKind = "error" | "timeout";
 
-type PendingLifecycleTerminal = {
-  kind: PendingLifecycleKind;
-  timer: NodeJS.Timeout;
+type PendingLifecycleParams = {
+  runId: string;
   endedAt: number;
   startedAt?: number;
+  cancellation?: true;
   error?: string;
   terminalReply?: SubagentCompletionRequest["terminalReply"];
 };
 
+type PendingLifecycleTerminal = PendingLifecycleParams & {
+  kind: PendingLifecycleKind;
+  timer: NodeJS.Timeout;
+};
+
 export function createPendingLifecycleScheduler(params: {
   runs: Map<string, SubagentRunRecord>;
   completeInBackground: (completion: SubagentCompletionRequest, source: string) => void;
@@ -38,16 +44,7 @@ export function createPendingLifecycleScheduler(params: {
     pendingByRunId.clear();
   }
 
-  function schedule(
-    kind: PendingLifecycleKind,
-    scheduleParams: {
-      runId: string;
-      endedAt: number;
-      startedAt?: number;
-      error?: string;
-      terminalReply?: SubagentCompletionRequest["terminalReply"];
-    },
-  ) {
+  function schedule(kind: PendingLifecycleKind, scheduleParams: PendingLifecycleParams) {
     clearKind(scheduleParams.runId);
     const timer = setTimeout(() => {
       const pending = pendingByRunId.get(scheduleParams.runId);
@@ -72,17 +69,26 @@ export function createPendingLifecycleScheduler(params: {
           runId: scheduleParams.runId,
           endedAt: pending.endedAt,
           outcome:
-            kind === "error" ? { status: "error", error: pending.error } : { status: "timeout" },
-          reason: kind === "error" ? SUBAGENT_ENDED_REASON_ERROR : SUBAGENT_ENDED_REASON_COMPLETE,
+            kind === "timeout"
+              ? { status: "timeout" }
+              : {
+                  status: "error",
+                  error: pending.cancellation ? "subagent run terminated" : pending.error,
+                },
+          reason: pending.cancellation
+            ? SUBAGENT_ENDED_REASON_KILLED
+            : kind === "error"
+              ? SUBAGENT_ENDED_REASON_ERROR
+              : SUBAGENT_ENDED_REASON_COMPLETE,
           sendFarewell: true,
           accountId: entry.requesterOrigin?.accountId,
           triggerCleanup: true,
           startedAt: pending.startedAt,
           terminalReply: pending.terminalReply,
         },
-        `lifecycle-${kind}-grace`,
+        pending.cancellation ? "lifecycle-cancellation-grace" : `lifecycle-${kind}-grace`,
       );
-    }, LIFECYCLE_RETRY_GRACE_MS);
+    }, AGENT_RUN_TERMINAL_RETRY_GRACE_MS);
     timer.unref?.();
     pendingByRunId.set(scheduleParams.runId, { ...scheduleParams, kind, timer });
   }
@@ -92,6 +98,8 @@ export function createPendingLifecycleScheduler(params: {
     clearError: (runId: string) => clearKind(runId, "error"),
     clearTimeout: (runId: string) => clearKind(runId, "timeout"),
     clearAll,
+    scheduleCancellation: (scheduleParams: Parameters<typeof schedule>[1]) =>
+      schedule("error", { ...scheduleParams, cancellation: true }),
     scheduleError: (scheduleParams: Parameters<typeof schedule>[1]) =>
       schedule("error", scheduleParams),
     scheduleTimeout: (scheduleParams: Parameters<typeof schedule>[1]) =>
diff --git a/src/agents/subagents/registry/subagent-registry-run-wait.ts b/src/agents/subagents/registry/subagent-registry-run-wait.ts
index 75ae4c14e19c..793c527510b9 100644
--- a/src/agents/subagents/registry/subagent-registry-run-wait.ts
+++ b/src/agents/subagents/registry/subagent-registry-run-wait.ts
@@ -6,15 +6,13 @@ import { callGateway } from "../../../gateway/call.js";
 import { isFastTestRuntimeEnv } from "../../../infra/env.js";
 import { createSubsystemLogger } from "../../../logging/subsystem.js";
 import type { DetachedTaskFindResult } from "../../../tasks/detached-task-runtime-contract.js";
-import {
-  buildAgentRunTerminalOutcomeFromWaitResult,
-  classifyAgentRunTerminalOutcome,
-} from "../../agent-run-terminal-outcome.js";
+import { buildAgentRunTerminalOutcomeFromWaitResult } from "../../agent-run-terminal-outcome.js";
 import { isRecoverableAgentWaitError, waitForAgentRun } from "../../run-wait.js";
 import {
   type SubagentRunOutcome,
   withSubagentOutcomeTiming,
 } from "../announce/subagent-announce-output.js";
+import { classifySubagentTerminalOutcome } from "../subagent-terminal-outcome.js";
 import { clearDeliveryState, ensureCompletionState } from "./subagent-delivery-state.js";
 import {
   SUBAGENT_ENDED_REASON_COMPLETE,
@@ -293,7 +291,7 @@ export class SubagentWaitManager {
       const waitBlocked = waitTerminalOutcome?.reason === "blocked";
       const waitAborted =
         waitTerminalOutcome !== undefined &&
-        classifyAgentRunTerminalOutcome(waitTerminalOutcome) === "cancellation";
+        classifySubagentTerminalOutcome(waitTerminalOutcome) === "cancellation";
       const waitStatus = waitTerminalOutcome?.status ?? wait.status;
       if (wait.yielded === true && waitStatus !== "timeout" && !waitBlocked) {
         this.options.clearPendingLifecycleError(runId);
diff --git a/src/agents/subagents/registry/subagent-registry.lifecycle-retry-grace.e2e.test.ts b/src/agents/subagents/registry/subagent-registry.lifecycle-retry-grace.e2e.test.ts
index b5a76c0bcbcb..ea4025ba6b8e 100644
--- a/src/agents/subagents/registry/subagent-registry.lifecycle-retry-grace.e2e.test.ts
+++ b/src/agents/subagents/registry/subagent-registry.lifecycle-retry-grace.e2e.test.ts
@@ -19,7 +19,11 @@ type LifecycleData = {
   endedAt?: number;
   aborted?: boolean;
   error?: string;
+  stopReason?: string;
   terminalReply?: AgentRunTerminalReplySnapshot;
+  status?: string;
+  timeoutPhase?: string;
+  providerStarted?: boolean;
 };
 type LifecycleEvent = {
   stream?: string;
@@ -840,28 +844,65 @@ describe("subagent registry lifecycle error grace", () => {
     expect(run.completion?.capturedAt).toBeTypeOf("number");
   });
 
-  it("completes with timeout status when aborted end event fires after grace window", async () => {
-    registerCompletionRun("run-timeout", "timeout", "timeout test");
-    setAssistantOutput("agent:main:subagent:timeout", "Partial output before timeout");
+  it("records a bare aborted end event as cancellation after retry grace", async () => {
+    registerCompletionRun("run-aborted", "aborted", "aborted test");
+    setAssistantOutput("agent:main:subagent:aborted", "Partial output before cancellation");
 
-    // Emit an end event with aborted=true which triggers the timeout grace path
-    emitLifecycleEvent("run-timeout", {
+    emitLifecycleEvent("run-aborted", {
       phase: "end",
       aborted: true,
       endedAt: 3_000,
-    } as LifecycleData & { aborted: boolean });
+    });
     await flushAsync();
+
     expect(getAgentCalls()).toHaveLength(0);
+    expect(
+      mod
+        .listSubagentRunsForRequester(MAIN_REQUESTER_SESSION_KEY)
+        .find((candidate) => candidate.runId === "run-aborted")?.execution.status,
+    ).toBe("running");
 
-    // Advance past the lifecycle timeout retry grace window
-    await vi.advanceTimersByTimeAsync(30_000);
+    await vi.advanceTimersByTimeAsync(15_000);
     await flushAsync();
 
-    await waitForAgentCallCount(1);
-
     const run = mod
       .listSubagentRunsForRequester(MAIN_REQUESTER_SESSION_KEY)
-      .find((candidate) => candidate.runId === "run-timeout");
+      .find((candidate) => candidate.runId === "run-aborted");
+    expect(run).toMatchObject({
+      endedReason: "subagent-killed",
+      execution: { outcome: { status: "error", error: "subagent run terminated" } },
+    });
+    expect(getAgentCalls()).toHaveLength(0);
+  });
+
+  it("announces a provider hard timeout from its canonical lifecycle metadata", async () => {
+    registerCompletionRun("run-provider-timeout", "provider-timeout", "provider timeout test");
+    setAssistantOutput(
+      "agent:main:subagent:provider-timeout",
+      "Partial output before provider timeout",
+    );
+
+    emitLifecycleEvent("run-provider-timeout", {
+      phase: "end",
+      aborted: true,
+      stopReason: "restart",
+      status: "timeout",
+      timeoutPhase: "provider",
+      providerStarted: true,
+      endedAt: 3_000,
+      error: "provider timed out",
+    });
+    await flushAsync();
+    expect(getAgentCalls()).toHaveLength(0);
+
+    await vi.advanceTimersByTimeAsync(30_000);
+    await flushAsync();
+    await waitForAgentCallCount(1);
+
+    expect(readFirstAnnounceOutcome()?.status).toBe("timeout");
+    const run = mod
+      .listSubagentRunsForRequester(MAIN_REQUESTER_SESSION_KEY)
+      .find((candidate) => candidate.runId === "run-provider-timeout");
     expect(run?.execution.outcome?.status).toBe("timeout");
   });
 
@@ -869,12 +910,15 @@ describe("subagent registry lifecycle error grace", () => {
     registerCompletionRun("run-timeout-cancel", "timeout-cancel", "timeout cancel test");
     setAssistantOutput("agent:main:subagent:timeout-cancel", "Final answer after recovery");
 
-    // Emit an aborted end event (starts timeout grace)
+    // Emit a structured timeout terminal (starts timeout grace).
     emitLifecycleEvent("run-timeout-cancel", {
       phase: "end",
       aborted: true,
+      status: "timeout",
+      timeoutPhase: "provider",
+      providerStarted: true,
       endedAt: 4_000,
-    } as LifecycleData & { aborted: boolean });
+    });
     await flushAsync();
     expect(getAgentCalls()).toHaveLength(0);
 
diff --git a/src/agents/subagents/registry/subagent-registry.persistence.resume.test.ts b/src/agents/subagents/registry/subagent-registry.persistence.resume.test.ts
index 162921eb0572..e86083242329 100644
--- a/src/agents/subagents/registry/subagent-registry.persistence.resume.test.ts
+++ b/src/agents/subagents/registry/subagent-registry.persistence.resume.test.ts
@@ -133,14 +133,19 @@ describe("subagent registry persistence resume", () => {
     });
   });
 
-  it("retries pending child delivery before a recovered requester-turn wake", async () => {
+  it.each([
+    { label: "successful", status: "ok" as const },
+    { label: "timed-out", status: "timeout" as const },
+  ])("retries pending $label child delivery after restart", async ({ label, status }) => {
     tempStateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-subagent-"));
     const stateDir = tempStateDir;
     await withEnvAsync({ OPENCLAW_STATE_DIR: stateDir }, async () => {
+      const runId = `run-pending-${label}-delivery`;
+      const childSessionKey = `agent:main:subagent:pending-${label}-delivery`;
       const run: SubagentRunRecord = {
-        runId: "run-pending-delivery",
+        runId,
         requesterTurnRunId: "run-requester",
-        childSessionKey: "agent:main:subagent:pending-delivery",
+        childSessionKey,
         requesterSessionKey: "agent:main:main",
         requesterDisplayKey: "main",
         task: "deliver before waking requester",
@@ -151,7 +156,7 @@ describe("subagent registry persistence resume", () => {
           status: "terminal",
           startedAt: 110,
           endedAt: 200,
-          outcome: { status: "ok" },
+          outcome: { status },
         },
         expectsCompletionMessage: true,
         completion: { required: true, resultText: "done", capturedAt: 200 },
@@ -160,12 +165,12 @@ describe("subagent registry persistence resume", () => {
           payload: {
             requesterSessionKey: "agent:main:main",
             requesterDisplayKey: "main",
-            childSessionKey: "agent:main:subagent:pending-delivery",
-            childRunId: "run-pending-delivery",
+            childSessionKey,
+            childRunId: runId,
             task: "deliver before waking requester",
             startedAt: 110,
             endedAt: 200,
-            outcome: { status: "ok" },
+            outcome: { status },
             expectsCompletionMessage: true,
           },
         },
@@ -176,8 +181,8 @@ describe("subagent registry persistence resume", () => {
         stateDir,
         agentId: "main",
         sessionKey: run.childSessionKey,
-        sessionId: "sess-pending-delivery",
-        defaultSessionId: "sess-pending-delivery",
+        sessionId: `sess-pending-${label}-delivery`,
+        defaultSessionId: `sess-pending-${label}-delivery`,
       });
 
       mod.initSubagentRegistry();
@@ -188,8 +193,9 @@ describe("subagent registry persistence resume", () => {
         interval: 10,
       });
       expect(announceSpy).toHaveBeenCalledWith(
-        expect.objectContaining({ childRunId: "run-pending-delivery" }),
+        expect.objectContaining({ childRunId: runId, outcome: { status } }),
       );
+      expect(mod.getSubagentRunByRunId(runId)?.execution.outcome).toEqual({ status });
     });
   });
 
diff --git a/src/agents/subagents/subagent-terminal-outcome.test.ts b/src/agents/subagents/subagent-terminal-outcome.test.ts
new file mode 100644
index 000000000000..2866d6739061
--- /dev/null
+++ b/src/agents/subagents/subagent-terminal-outcome.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { buildAgentRunTerminalOutcome } from "../agent-run-terminal-outcome.js";
+import { classifySubagentTerminalOutcome } from "./subagent-terminal-outcome.js";
+
+describe("classifySubagentTerminalOutcome", () => {
+  it("preserves provider timeout attribution over a retained restart marker", () => {
+    const outcome = buildAgentRunTerminalOutcome({
+      status: "timeout",
+      stopReason: "restart",
+      timeoutPhase: "provider",
+      providerStarted: true,
+    });
+
+    expect(classifySubagentTerminalOutcome(outcome)).toBe("timeout");
+  });
+
+  it("applies restart cancellation over incomplete liveness projections", () => {
+    const outcome = buildAgentRunTerminalOutcome({
+      status: "error",
+      stopReason: "restart",
+      livenessState: "blocked",
+    });
+
+    expect(classifySubagentTerminalOutcome(outcome)).toBe("cancellation");
+  });
+});
diff --git a/src/agents/subagents/subagent-terminal-outcome.ts b/src/agents/subagents/subagent-terminal-outcome.ts
new file mode 100644
index 000000000000..c8069f10fd7a
--- /dev/null
+++ b/src/agents/subagents/subagent-terminal-outcome.ts
@@ -0,0 +1,13 @@
+import {
+  classifyAgentRunTerminalOutcome,
+  type AgentRunTerminalOutcome,
+} from "../agent-run-terminal-outcome.js";
+import { isAbortedAgentStopReason } from "../run-termination.js";
+
+/** Subagents apply explicit cancellation ownership after canonical timeout attribution. */
+export function classifySubagentTerminalOutcome(outcome: AgentRunTerminalOutcome) {
+  const classification = classifyAgentRunTerminalOutcome(outcome);
+  return classification === "timeout" || !isAbortedAgentStopReason(outcome.stopReason)
+    ? classification
+    : "cancellation";
+}

From 87d02a90897636c9da03bc7f2d25c739ab964fd0 Mon Sep 17 00:00:00 2001
From: Masato Hoshino <g515hoshino@gmail.com>
Date: Sat, 22 Aug 2026 04:03:36 +0900
Subject: [PATCH 072/124] fix(logs): report truncated channel tails (#123699)

Punchcard-Session: golden-timber-willow-68
---
 src/commands/channels.logs.test.ts | 16 ++++++++++++++++
 src/commands/channels/logs.ts      |  7 +++++--
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/src/commands/channels.logs.test.ts b/src/commands/channels.logs.test.ts
index 8917f586c675..3be07753b9f2 100644
--- a/src/commands/channels.logs.test.ts
+++ b/src/commands/channels.logs.test.ts
@@ -53,6 +53,7 @@ function readJsonPayload() {
   return JSON.parse(String(runtime.log.mock.calls[0]?.[0])) as {
     file: string;
     channel: string;
+    truncated: boolean;
     lines: Array<{ message: string; raw: string }>;
   };
 }
@@ -216,6 +217,21 @@ describe("channelsLogsCommand", () => {
     ]);
   });
 
+  it("reports when the byte window omits all matching channel records", async () => {
+    const omitted = logLine({ module: "gateway/channels/slack/send", message: "omitted" });
+    const filler = logLine({ module: "gateway/health", message: "x".repeat(1000) });
+    await fs.writeFile(logPath, `${omitted}\n${filler.repeat(1100)}`);
+
+    await channelsLogsCommand({ channel: "slack", json: true }, runtime);
+    expect(readJsonPayload()).toMatchObject({ truncated: true, lines: [] });
+
+    runtime.log.mockClear();
+    await channelsLogsCommand({ channel: "slack" }, runtime);
+    expect(runtime.log.mock.calls.flat().join("\n")).toContain(
+      "Log tail truncated; earlier entries were omitted.",
+    );
+  });
+
   it("treats an omitted channel filter as all", async () => {
     await fs.writeFile(
       logPath,
diff --git a/src/commands/channels/logs.ts b/src/commands/channels/logs.ts
index 7658a7e98907..8a251c139e94 100644
--- a/src/commands/channels/logs.ts
+++ b/src/commands/channels/logs.ts
@@ -104,10 +104,10 @@ export async function channelsLogsCommand(
     maxBytes: MAX_BYTES,
     filter: (line) => matchesChannel(line, filter),
   });
-  const lines = tail.lines;
+  const { lines, truncated } = tail;
 
   if (opts.json) {
-    writeRuntimeJson(runtime, { file: tail.file, channel, lines });
+    writeRuntimeJson(runtime, { file: tail.file, channel, truncated, lines });
     return;
   }
 
@@ -115,6 +115,9 @@ export async function channelsLogsCommand(
   if (channel !== "all") {
     runtime.log(theme.info(`Channel: ${channel}`));
   }
+  if (truncated) {
+    runtime.log(theme.warn("Log tail truncated; earlier entries were omitted."));
+  }
   if (lines.length === 0) {
     runtime.log(theme.muted("No matching log lines."));
     return;

From 98c02e0112bfb2447caf4018a7f3302b41e7d1d1 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 12:07:03 -0700
Subject: [PATCH 073/124] fix(cli): tell config get apart a typo from an unset
 key (#127369)

config get answered identically for a real-but-unset schema path and a
path that does not exist, and pointed both at config validate, which only
reports whether the current file parses.

Use the schema runConfigGet already builds to split the two cases: a known
path reports that it is unset and offers a runnable config set command for
that exact path; an unknown path points at config schema. Exit code stays 1
for both, in text and --json.
---
 src/cli/config-cli-path.ts |   7 +++
 src/cli/config-cli.test.ts | 100 +++++++++++++++++++++++++++++++++----
 src/cli/config-cli.ts      |  15 +++---
 3 files changed, 106 insertions(+), 16 deletions(-)

diff --git a/src/cli/config-cli-path.ts b/src/cli/config-cli-path.ts
index 98b1e292fd71..50c62ef6f883 100644
--- a/src/cli/config-cli-path.ts
+++ b/src/cli/config-cli-path.ts
@@ -320,6 +320,13 @@ function schemasAtPath(
   return schemas;
 }
 
+export function isConfigSchemaPath(
+  schema: JsonSchemaRecord | undefined,
+  path: readonly PathSegment[],
+): boolean {
+  return schemasAtPath(schema, path).length > 0;
+}
+
 function schemaPrefersArrayAtPath(
   schema: JsonSchemaRecord | undefined,
   path: readonly PathSegment[],
diff --git a/src/cli/config-cli.test.ts b/src/cli/config-cli.test.ts
index b4995c682068..6b27d541ba06 100644
--- a/src/cli/config-cli.test.ts
+++ b/src/cli/config-cli.test.ts
@@ -98,7 +98,43 @@ vi.mock("../secrets/resolve.js", () => ({
 }));
 
 vi.mock("../config/runtime-schema.js", () => ({
-  buildRuntimeConfigSchemaFromRegistry: () => ({ uiHints: {} }),
+  buildRuntimeConfigSchemaFromRegistry: () => ({
+    schema: {
+      type: "object",
+      properties: {
+        models: {
+          type: "object",
+          properties: {
+            providers: {
+              type: "object",
+              additionalProperties: {
+                type: "object",
+                properties: {
+                  models: {
+                    type: "array",
+                    items: {
+                      type: "object",
+                      properties: { id: { type: "string" } },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+        gateway: {
+          type: "object",
+          properties: {
+            bind: { type: "string" },
+            port: { type: "number" },
+          },
+        },
+      },
+    },
+    uiHints: {},
+    version: "test",
+    generatedAt: "2026-03-25T00:00:00.000Z",
+  }),
   readBestEffortRuntimeConfigSchema: () => mockReadBestEffortRuntimeConfigSchema(),
 }));
 
@@ -1303,6 +1339,7 @@ describe("config cli", () => {
 
       expect(mockReadConfigFileSnapshot).toHaveBeenCalledWith({ observe: false });
       expect(parseLastLogPayload()).toBe(18789);
+      expect(mockExit).not.toHaveBeenCalled();
     });
 
     it("redacts sensitive values", async () => {
@@ -1358,19 +1395,64 @@ describe("config cli", () => {
       expect(mockWriteStdout).toHaveBeenCalledWith("60\n");
     });
 
-    it("outputs JSON error to stdout when path is not found and --json is set", async () => {
+    it.each([
+      {
+        name: "valid but unset schema path",
+        path: "gateway.bind",
+        message:
+          "Config path is valid but unset: gateway.bind. The runtime default applies until you set an authored value with openclaw config set gateway.bind <value>.",
+      },
+      {
+        name: "valid but unset array path",
+        path: "models.providers.example.models[0].id",
+        message:
+          "Config path is valid but unset: models.providers.example.models[0].id. The runtime default applies until you set an authored value with openclaw config set 'models.providers.example.models[0].id' <value>.",
+      },
+      {
+        name: "unknown path",
+        path: "nonexistent.path",
+        message:
+          "Unknown config path: nonexistent.path. Run openclaw config schema to inspect valid paths.",
+      },
+    ])("reports a $name to the operator", async (testCase) => {
       setGatewaySnapshot();
 
-      await expect(
-        runConfigCommand(["config", "get", "nonexistent.path", "--json"]),
-      ).rejects.toThrow(ExitError);
+      await expect(runConfigCommand(["config", "get", testCase.path])).rejects.toThrow(ExitError);
+
+      expectErrorIncludes(testCase.message);
+      expect(mockExit).toHaveBeenCalledWith(1);
+      expect(mockLog).not.toHaveBeenCalled();
+    });
+
+    it.each([
+      {
+        name: "valid but unset schema path",
+        path: "gateway.bind",
+        message:
+          "Config path is valid but unset: gateway.bind. The runtime default applies until you set an authored value with openclaw config set gateway.bind <value>.",
+      },
+      {
+        name: "unknown path",
+        path: "nonexistent.path",
+        message:
+          "Unknown config path: nonexistent.path. Run openclaw config schema to inspect valid paths.",
+      },
+    ])("outputs a JSON error for a $name", async (testCase) => {
+      setGatewaySnapshot();
+
+      await expect(runConfigCommand(["config", "get", testCase.path, "--json"])).rejects.toThrow(
+        ExitError,
+      );
 
       expect(mockError).not.toHaveBeenCalled();
-      const payload = parseLastLogPayload() as { error: { type: string; message: string } };
-      expect(payload.error).toEqual({
-        type: "cli_error",
-        message: "Config path not found: nonexistent.path",
+      expect(parseLastLogPayload()).toEqual({
+        ok: false,
+        error: {
+          type: "cli_error",
+          message: testCase.message,
+        },
       });
+      expect(mockExit).toHaveBeenCalledWith(1);
     });
 
     it.each([
diff --git a/src/cli/config-cli.ts b/src/cli/config-cli.ts
index dbabd7010279..1481311f21b2 100644
--- a/src/cli/config-cli.ts
+++ b/src/cli/config-cli.ts
@@ -38,6 +38,7 @@ import { normalizeConfigMutationModelRefs } from "./config-cli-model-normalizati
 import {
   formatConfigUnsetMissingPathMessage,
   getAtPath,
+  isConfigSchemaPath,
   parseConfigSetPath,
   unsetAtPath,
 } from "./config-cli-path.js";
@@ -67,6 +68,7 @@ import {
 import { resolveConfigSetMode } from "./config-set-parser.js";
 import { formatCliJsonFailure } from "./failure-output.js";
 import { setCommandJsonMode } from "./program/json-mode.js";
+import { quoteCliArg } from "./quote-cli-arg.js";
 
 export { parseConfigSetPath } from "./config-cli-path.js";
 
@@ -171,21 +173,20 @@ export async function runConfigGet(opts: { path: string; json?: boolean; runtime
     if (!pluginMetadataSnapshot) {
       throw new Error("Config plugin metadata unavailable; refusing to display config values.");
     }
-    const { uiHints } = buildRuntimeConfigSchemaFromRegistry(
+    const { schema, uiHints } = buildRuntimeConfigSchemaFromRegistry(
       pluginMetadataSnapshot.manifestRegistry,
     );
     const res = getAtPath(redactConfigObject(snapshot.config, uiHints), parsedPath);
     if (!res.found) {
+      const message = isConfigSchemaPath(schema, parsedPath)
+        ? `Config path is valid but unset: ${opts.path}. The runtime default applies until you set an authored value with ${formatCliCommand(`openclaw config set ${quoteCliArg(opts.path)} <value>`)}.`
+        : `Unknown config path: ${opts.path}. Run ${formatCliCommand("openclaw config schema")} to inspect valid paths.`;
       if (opts.json) {
-        writeRuntimeJson(runtime, formatCliJsonFailure(`Config path not found: ${opts.path}`));
+        writeRuntimeJson(runtime, formatCliJsonFailure(message));
         runtime.exit(1);
         return;
       }
-      runtime.error(
-        danger(
-          `Config path not found: ${opts.path}. Run ${formatCliCommand("openclaw config validate")} to inspect config shape.`,
-        ),
-      );
+      runtime.error(danger(message));
       runtime.exit(1);
       return;
     }

From 5afc6fb0fb0345516b004e3d593cd507ea5e5af0 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 12:11:59 -0700
Subject: [PATCH 074/124] fix(cli): give hooks enable/disable failures a next
 step (#127370)

* fix(cli): give hooks enable/disable failures a next step

resolveHookForToggle threw bare messages for not-found, ambiguous, and
ineligible hooks while formatHookInfo, the sibling lookup in the same file,
already pointed operators at openclaw hooks list.

Name the colliding candidates, the missing requirements, and the install
route using data the hook status entry already carries, bounded through the
existing summarizeStringEntries helper.

* refactor(cli): split hooks report rendering out of hooks-cli

The new toggle diagnostics pushed src/cli/hooks-cli.ts to 709 lines, over
the 700-line cap. Move the hooks list/info/check renderers and their
formatting helpers to hooks-cli.format.ts so command wiring and report
rendering each stay readable; no suppression added.
---
 src/cli/hooks-cli.format.ts      | 358 +++++++++++++++++++++++++++++
 src/cli/hooks-cli.test.ts        |   8 +-
 src/cli/hooks-cli.toggle.test.ts |  69 +++++-
 src/cli/hooks-cli.ts             | 382 +++----------------------------
 4 files changed, 458 insertions(+), 359 deletions(-)
 create mode 100644 src/cli/hooks-cli.format.ts

diff --git a/src/cli/hooks-cli.format.ts b/src/cli/hooks-cli.format.ts
new file mode 100644
index 000000000000..ffbf43616a50
--- /dev/null
+++ b/src/cli/hooks-cli.format.ts
@@ -0,0 +1,358 @@
+// Renders the `openclaw hooks` list, info, and check reports.
+// Kept apart from command wiring so each surface stays readable and under the file-size cap.
+
+import {
+  decorativeEmoji,
+  decorativePrefix,
+} from "../../packages/terminal-core/src/decorative-emoji.js";
+import { getTerminalTableWidth, renderTable } from "../../packages/terminal-core/src/table.js";
+import { theme } from "../../packages/terminal-core/src/theme.js";
+import type { HookStatusEntry, HookStatusReport } from "../hooks/hooks-status.js";
+import { summarizeStringEntries } from "../shared/string-sample.js";
+import { shortenHomePath } from "../utils.js";
+import { formatCliCommand } from "./command-format.js";
+
+export type HooksListOptions = {
+  agent?: string;
+  json?: boolean;
+  eligible?: boolean;
+  verbose?: boolean;
+};
+
+export type HookInfoOptions = {
+  agent?: string;
+  json?: boolean;
+};
+
+export type HooksCheckOptions = {
+  agent?: string;
+  json?: boolean;
+};
+
+function formatHookStatus(hook: HookStatusEntry): string {
+  if (hook.loadable) {
+    return theme.success("✓ ready");
+  }
+  if (!hook.enabledByConfig) {
+    return theme.warn(decorativePrefix("⏸", "disabled"));
+  }
+  return theme.error(`✗ ${formatHookBlockedStatusReason(hook)}`);
+}
+
+function formatHookBlockedStatusReason(hook: HookStatusEntry): string {
+  return hook.blockedReason && hook.blockedReason !== "missing requirements"
+    ? hook.blockedReason
+    : "missing";
+}
+
+function formatHookInfoBlockedStatusReason(hook: HookStatusEntry): string {
+  const reason =
+    hook.blockedReason && hook.blockedReason !== "missing requirements"
+      ? hook.blockedReason
+      : "missing requirements";
+  return reason ? `${reason[0]?.toUpperCase() ?? ""}${reason.slice(1)}` : reason;
+}
+
+function formatHookName(hook: HookStatusEntry): string {
+  const emoji = hook.emoji ?? decorativeEmoji("🔗");
+  const name = theme.command(hook.name);
+  return emoji ? `${emoji} ${name}` : name;
+}
+
+function formatHookSource(hook: HookStatusEntry): string {
+  if (!hook.managedByPlugin) {
+    return hook.source;
+  }
+  return `plugin:${hook.pluginId ?? "unknown"}`;
+}
+
+export function formatHookMissingSummary(hook: HookStatusEntry, itemLimit?: number): string {
+  const formatEntries = (entries: string[]) =>
+    itemLimit === undefined
+      ? entries.join(", ")
+      : summarizeStringEntries({ entries, limit: itemLimit });
+  const missing: string[] = [];
+  if (hook.enabledByConfig && hook.blockedReason && hook.blockedReason !== "missing requirements") {
+    missing.push(hook.blockedReason);
+  }
+  if (hook.missing.bins.length > 0) {
+    missing.push(`bins: ${formatEntries(hook.missing.bins)}`);
+  }
+  if (hook.missing.anyBins.length > 0) {
+    missing.push(`anyBins: ${formatEntries(hook.missing.anyBins)}`);
+  }
+  if (hook.missing.env.length > 0) {
+    missing.push(`env: ${formatEntries(hook.missing.env)}`);
+  }
+  if (hook.missing.config.length > 0) {
+    missing.push(`config: ${formatEntries(hook.missing.config)}`);
+  }
+  if (hook.missing.os.length > 0) {
+    missing.push(`os: ${formatEntries(hook.missing.os)}`);
+  }
+  return missing.join("; ");
+}
+
+/**
+ * Format the hooks list output
+ */
+export function formatHooksList(report: HookStatusReport, opts: HooksListOptions): string {
+  const hooks = opts.eligible ? report.hooks.filter((h) => h.loadable) : report.hooks;
+
+  if (opts.json) {
+    const jsonReport = {
+      workspaceDir: report.workspaceDir,
+      managedHooksDir: report.managedHooksDir,
+      hooks: hooks.map((h) => ({
+        name: h.name,
+        description: h.description,
+        emoji: h.emoji,
+        eligible: h.loadable,
+        disabled: !h.enabledByConfig,
+        enabledByConfig: h.enabledByConfig,
+        requirementsSatisfied: h.requirementsSatisfied,
+        loadable: h.loadable,
+        blockedReason: h.blockedReason,
+        source: h.source,
+        pluginId: h.pluginId,
+        events: h.events,
+        unknownEvents: h.unknownEvents,
+        homepage: h.homepage,
+        missing: h.missing,
+        managedByPlugin: h.managedByPlugin,
+      })),
+    };
+    return JSON.stringify(jsonReport, null, 2);
+  }
+
+  if (hooks.length === 0) {
+    const message = opts.eligible
+      ? `No eligible hooks found. Run \`${formatCliCommand("openclaw hooks list")}\` to see all hooks.`
+      : "No hooks found.";
+    return message;
+  }
+
+  const eligible = hooks.filter((h) => h.loadable);
+  const tableWidth = getTerminalTableWidth();
+  const rows = hooks.map((hook) => {
+    const missing = formatHookMissingSummary(hook);
+    return {
+      Status: formatHookStatus(hook),
+      Hook: formatHookName(hook),
+      Description: theme.muted(hook.description),
+      Source: formatHookSource(hook),
+      Missing: missing ? theme.warn(missing) : "",
+    };
+  });
+
+  const columns = [
+    { key: "Status", header: "Status", minWidth: 10 },
+    { key: "Hook", header: "Hook", minWidth: 18, flex: true },
+    { key: "Description", header: "Description", minWidth: 24, flex: true },
+    { key: "Source", header: "Source", minWidth: 12, flex: true },
+  ];
+  if (opts.verbose) {
+    columns.push({ key: "Missing", header: "Missing", minWidth: 18, flex: true });
+  }
+
+  const lines: string[] = [];
+  lines.push(
+    `${theme.heading("Hooks")} ${theme.muted(`(${eligible.length}/${hooks.length} ready)`)}`,
+  );
+  lines.push(
+    renderTable({
+      width: tableWidth,
+      columns,
+      rows,
+    }).trimEnd(),
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Format detailed info for a single hook
+ */
+export function formatHookInfo(
+  report: HookStatusReport,
+  hookName: string,
+  opts: HookInfoOptions,
+): string {
+  const hook = report.hooks.find((h) => h.name === hookName || h.hookKey === hookName);
+
+  if (!hook) {
+    if (opts.json) {
+      return JSON.stringify({ error: "not found", hook: hookName }, null, 2);
+    }
+    return `Hook "${hookName}" not found. Run \`${formatCliCommand("openclaw hooks list")}\` to see available hooks.`;
+  }
+
+  if (opts.json) {
+    return JSON.stringify(
+      {
+        ...hook,
+        eligible: hook.loadable,
+        disabled: !hook.enabledByConfig,
+      },
+      null,
+      2,
+    );
+  }
+
+  const lines: string[] = [];
+  const emoji = hook.emoji ?? decorativeEmoji("🔗");
+  const status = hook.loadable
+    ? theme.success("✓ Ready")
+    : !hook.enabledByConfig
+      ? theme.warn(decorativePrefix("⏸", "Disabled"))
+      : theme.error(`✗ ${formatHookInfoBlockedStatusReason(hook)}`);
+
+  lines.push(`${emoji ? `${emoji} ` : ""}${theme.heading(hook.name)} ${status}`);
+  lines.push("");
+  lines.push(hook.description);
+  lines.push("");
+
+  // Details
+  lines.push(theme.heading("Details:"));
+  if (hook.managedByPlugin) {
+    lines.push(`${theme.muted("  Source:")} ${hook.source} (${hook.pluginId ?? "unknown"})`);
+  } else {
+    lines.push(`${theme.muted("  Source:")} ${hook.source}`);
+  }
+  lines.push(`${theme.muted("  Path:")} ${shortenHomePath(hook.filePath)}`);
+  lines.push(`${theme.muted("  Handler:")} ${shortenHomePath(hook.handlerPath)}`);
+  if (hook.homepage) {
+    lines.push(`${theme.muted("  Homepage:")} ${hook.homepage}`);
+  }
+  if (hook.events.length > 0) {
+    lines.push(`${theme.muted("  Events:")} ${hook.events.join(", ")}`);
+  }
+  if (hook.unknownEvents.length > 0) {
+    lines.push(
+      theme.warn(
+        `  ⚠ Event${hook.unknownEvents.length === 1 ? "" : "s"} not emitted by core (likely typo): ${hook.unknownEvents.join(", ")}`,
+      ),
+    );
+  }
+  if (hook.managedByPlugin) {
+    lines.push(theme.muted("  Managed by plugin; enable/disable via hooks CLI not available."));
+  }
+  if (hook.blockedReason) {
+    lines.push(`${theme.muted("  Blocked reason:")} ${hook.blockedReason}`);
+  }
+
+  // Requirements
+  const hasRequirements =
+    hook.requirements.bins.length > 0 ||
+    hook.requirements.anyBins.length > 0 ||
+    hook.requirements.env.length > 0 ||
+    hook.requirements.config.length > 0 ||
+    hook.requirements.os.length > 0;
+
+  if (hasRequirements) {
+    lines.push("");
+    lines.push(theme.heading("Requirements:"));
+    if (hook.requirements.bins.length > 0) {
+      const binsStatus = hook.requirements.bins.map((bin) => {
+        const missing = hook.missing.bins.includes(bin);
+        return missing ? theme.error(`✗ ${bin}`) : theme.success(`✓ ${bin}`);
+      });
+      lines.push(`${theme.muted("  Binaries:")} ${binsStatus.join(", ")}`);
+    }
+    if (hook.requirements.anyBins.length > 0) {
+      const anyBinsStatus =
+        hook.missing.anyBins.length > 0
+          ? theme.error(`✗ (any of: ${hook.requirements.anyBins.join(", ")})`)
+          : theme.success(`✓ (any of: ${hook.requirements.anyBins.join(", ")})`);
+      lines.push(`${theme.muted("  Any binary:")} ${anyBinsStatus}`);
+    }
+    if (hook.requirements.env.length > 0) {
+      const envStatus = hook.requirements.env.map((env) => {
+        const missing = hook.missing.env.includes(env);
+        return missing ? theme.error(`✗ ${env}`) : theme.success(`✓ ${env}`);
+      });
+      lines.push(`${theme.muted("  Environment:")} ${envStatus.join(", ")}`);
+    }
+    if (hook.requirements.config.length > 0) {
+      const configStatus = hook.configChecks.map((check) => {
+        return check.satisfied ? theme.success(`✓ ${check.path}`) : theme.error(`✗ ${check.path}`);
+      });
+      lines.push(`${theme.muted("  Config:")} ${configStatus.join(", ")}`);
+    }
+    if (hook.requirements.os.length > 0) {
+      const osStatus =
+        hook.missing.os.length > 0
+          ? theme.error(`✗ (${hook.requirements.os.join(", ")})`)
+          : theme.success(`✓ (${hook.requirements.os.join(", ")})`);
+      lines.push(`${theme.muted("  OS:")} ${osStatus}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format check output
+ */
+export function formatHooksCheck(report: HookStatusReport, opts: HooksCheckOptions): string {
+  if (opts.json) {
+    const eligible = report.hooks.filter((h) => h.loadable);
+    const notEligible = report.hooks.filter((h) => !h.loadable);
+    return JSON.stringify(
+      {
+        total: report.hooks.length,
+        eligible: eligible.length,
+        notEligible: notEligible.length,
+        hooks: {
+          eligible: eligible.map((h) => h.name),
+          notEligible: notEligible.map((h) => ({
+            name: h.name,
+            blockedReason: h.blockedReason,
+            missing: h.missing,
+          })),
+        },
+      },
+      null,
+      2,
+    );
+  }
+
+  const eligible = report.hooks.filter((h) => h.loadable);
+  const notEligible = report.hooks.filter((h) => !h.loadable);
+
+  const lines: string[] = [];
+  lines.push(theme.heading("Hooks Status"));
+  lines.push("");
+  lines.push(`${theme.muted("Total hooks:")} ${report.hooks.length}`);
+  lines.push(`${theme.success("Ready:")} ${eligible.length}`);
+  lines.push(`${theme.warn("Not ready:")} ${notEligible.length}`);
+
+  if (notEligible.length > 0) {
+    lines.push("");
+    lines.push(theme.heading("Hooks not ready:"));
+    for (const hook of notEligible) {
+      const reasons = [];
+      if (hook.blockedReason && hook.blockedReason !== "missing requirements") {
+        reasons.push(hook.blockedReason);
+      }
+      if (hook.missing.bins.length > 0) {
+        reasons.push(`bins: ${hook.missing.bins.join(", ")}`);
+      }
+      if (hook.missing.anyBins.length > 0) {
+        reasons.push(`anyBins: ${hook.missing.anyBins.join(", ")}`);
+      }
+      if (hook.missing.env.length > 0) {
+        reasons.push(`env: ${hook.missing.env.join(", ")}`);
+      }
+      if (hook.missing.config.length > 0) {
+        reasons.push(`config: ${hook.missing.config.join(", ")}`);
+      }
+      if (hook.missing.os.length > 0) {
+        reasons.push(`os: ${hook.missing.os.join(", ")}`);
+      }
+      const emoji = hook.emoji ?? decorativeEmoji("🔗");
+      lines.push(`  ${emoji ? `${emoji} ` : ""}${hook.name} - ${reasons.join("; ")}`);
+    }
+  }
+
+  return lines.join("\n");
+}
diff --git a/src/cli/hooks-cli.test.ts b/src/cli/hooks-cli.test.ts
index a3dc5fa36eb4..8bf25ce6f742 100644
--- a/src/cli/hooks-cli.test.ts
+++ b/src/cli/hooks-cli.test.ts
@@ -3,12 +3,8 @@ import { expectDefined } from "@openclaw/normalization-core";
 import { Command } from "commander";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { HookStatusReport } from "../hooks/hooks-status.js";
-import {
-  formatHookInfo,
-  formatHooksCheck,
-  formatHooksList,
-  registerHooksCli,
-} from "./hooks-cli.js";
+import { formatHookInfo, formatHooksCheck, formatHooksList } from "./hooks-cli.format.js";
+import { registerHooksCli } from "./hooks-cli.js";
 import { createEmptyInstallChecks } from "./requirements-test-fixtures.js";
 
 const runPluginInstallCommandMock = vi.hoisted(() => vi.fn());
diff --git a/src/cli/hooks-cli.toggle.test.ts b/src/cli/hooks-cli.toggle.test.ts
index 1f5742875a35..03c9cbd688bc 100644
--- a/src/cli/hooks-cli.toggle.test.ts
+++ b/src/cli/hooks-cli.toggle.test.ts
@@ -285,8 +285,73 @@ describe("hooks CLI metadata config keys", () => {
       }),
     ).rejects.toThrow("__exit__:1");
 
-    expect(capture.runtimeErrors.at(-1)).toContain(
-      `Hook "${testCase.identifier}" is ambiguous; use a unique hook name or hook key`,
+    expect(capture.runtimeErrors.at(-1)).toBe(
+      `Error: Hook "${testCase.identifier}" is ambiguous; matches: ${testCase.hooks
+        .map((candidate) => `${candidate.name} (${candidate.hookKey})`)
+        .join(", ")}. Use a unique hook name or hook key.`,
+    );
+    expect(mocks.replaceConfigFile).not.toHaveBeenCalled();
+  });
+
+  it("bounds ambiguous hook candidates", async () => {
+    const hooks = Array.from({ length: 7 }, (_, index) => ({
+      ...hook,
+      name: "shared-name",
+      hookKey: `key-${index + 1}`,
+    }));
+    mocks.buildWorkspaceHookStatus.mockReturnValue({ ...report, hooks });
+
+    await expect(
+      createHooksProgram().parseAsync(["hooks", "disable", "shared-name"], { from: "user" }),
+    ).rejects.toThrow("__exit__:1");
+
+    expect(capture.runtimeErrors.at(-1)).toBe(
+      'Error: Hook "shared-name" is ambiguous; matches: shared-name (key-1), shared-name (key-2), shared-name (key-3), shared-name (key-4), shared-name (key-5) (+2). Use a unique hook name or hook key.',
+    );
+    expect(mocks.replaceConfigFile).not.toHaveBeenCalled();
+  });
+
+  it.each(["enable", "disable"])(
+    "gives the recovery command for an unknown hook on %s",
+    async (action) => {
+      mocks.buildWorkspaceHookStatus.mockReturnValue({ ...report, hooks: [] });
+
+      await expect(
+        createHooksProgram().parseAsync(["hooks", action, "missing-hook"], { from: "user" }),
+      ).rejects.toThrow("__exit__:1");
+
+      expect(capture.runtimeErrors.at(-1)).toBe(
+        'Error: Hook "missing-hook" not found. Run `openclaw hooks list` to see available hooks.',
+      );
+      expect(mocks.replaceConfigFile).not.toHaveBeenCalled();
+    },
+  );
+
+  it("names missing requirements and the available install route", async () => {
+    const ineligibleHook: HookStatusEntry = {
+      ...hook,
+      requirementsSatisfied: false,
+      loadable: false,
+      blockedReason: "missing requirements",
+      missing: {
+        bins: ["missing-bin"],
+        anyBins: ["missing-any-a", "missing-any-b"],
+        env: ["MISSING_ENV"],
+        config: ["hooks.demo.enabled"],
+        os: ["linux"],
+      },
+      install: [
+        { id: "demo-npm", kind: "npm", label: "Install @openclaw/demo-hook (npm)", bins: [] },
+      ],
+    };
+    mocks.buildWorkspaceHookStatus.mockReturnValue({ ...report, hooks: [ineligibleHook] });
+
+    await expect(
+      createHooksProgram().parseAsync(["hooks", "enable", "display-name"], { from: "user" }),
+    ).rejects.toThrow("__exit__:1");
+
+    expect(capture.runtimeErrors.at(-1)).toBe(
+      'Error: Hook "display-name" is not eligible; missing bins: missing-bin; anyBins: missing-any-a, missing-any-b; env: MISSING_ENV; config: hooks.demo.enabled; os: linux. Install options: Install @openclaw/demo-hook (npm). Run `openclaw hooks info display-name` for details.',
     );
     expect(mocks.replaceConfigFile).not.toHaveBeenCalled();
   });
diff --git a/src/cli/hooks-cli.ts b/src/cli/hooks-cli.ts
index 71949f441bb7..355606128567 100644
--- a/src/cli/hooks-cli.ts
+++ b/src/cli/hooks-cli.ts
@@ -3,12 +3,8 @@ import {
   GATEWAY_CLIENT_MODES,
   GATEWAY_CLIENT_NAMES,
 } from "../../packages/gateway-protocol/src/client-info.js";
-import {
-  decorativeEmoji,
-  decorativePrefix,
-} from "../../packages/terminal-core/src/decorative-emoji.js";
+import { decorativePrefix } from "../../packages/terminal-core/src/decorative-emoji.js";
 import { formatDocsLink } from "../../packages/terminal-core/src/links.js";
-import { getTerminalTableWidth, renderTable } from "../../packages/terminal-core/src/table.js";
 import { theme } from "../../packages/terminal-core/src/theme.js";
 import {
   resolveAgentWorkspaceDir,
@@ -30,32 +26,24 @@ import { loadGatewayStartupPluginPlanWithMetadata } from "../plugins/channel-plu
 import { buildPluginDiagnosticsReport } from "../plugins/status.js";
 import { normalizeAgentId } from "../routing/session-key.js";
 import { defaultRuntime } from "../runtime.js";
-import { shortenHomePath } from "../utils.js";
+import { summarizeStringEntries } from "../shared/string-sample.js";
 import { resolveOptionFromCommand } from "./cli-utils.js";
 import { formatCliCommand } from "./command-format.js";
 import { rethrowExpectedCliError } from "./failure-output.js";
+import {
+  formatHookInfo,
+  formatHookMissingSummary,
+  formatHooksCheck,
+  formatHooksList,
+  type HookInfoOptions,
+  type HooksCheckOptions,
+  type HooksListOptions,
+} from "./hooks-cli.format.js";
 import { runNativeHookRelayCli, type NativeHookRelayCliOptions } from "./native-hook-relay-cli.js";
 import { requestExitAfterOneShotOutput } from "./one-shot-exit.js";
 import { runPluginInstallCommand } from "./plugins-install-command.js";
 import { runPluginUpdateCommand } from "./plugins-update-command.js";
 
-export type HooksListOptions = {
-  agent?: string;
-  json?: boolean;
-  eligible?: boolean;
-  verbose?: boolean;
-};
-
-export type HookInfoOptions = {
-  agent?: string;
-  json?: boolean;
-};
-
-export type HooksCheckOptions = {
-  agent?: string;
-  json?: boolean;
-};
-
 type HooksUpdateOptions = {
   acknowledgeInstallPolicyWarning?: boolean;
   all?: boolean;
@@ -163,11 +151,19 @@ function resolveHookForToggle(
   const matches =
     nameMatches.length > 0 ? nameMatches : report.hooks.filter((hook) => hook.hookKey === hookName);
   if (matches.length > 1) {
-    throw new Error(`Hook "${hookName}" is ambiguous; use a unique hook name or hook key`);
+    const candidates = summarizeStringEntries({
+      entries: matches.map((hook) => `${hook.name} (${hook.hookKey})`),
+      limit: 5,
+    });
+    throw new Error(
+      `Hook "${hookName}" is ambiguous; matches: ${candidates}. Use a unique hook name or hook key.`,
+    );
   }
   const hook = matches[0];
   if (!hook) {
-    throw new Error(`Hook "${hookName}" not found`);
+    throw new Error(
+      `Hook "${hookName}" not found. Run \`${formatCliCommand("openclaw hooks list")}\` to see available hooks.`,
+    );
   }
   if (hook.managedByPlugin) {
     throw new Error(
@@ -175,7 +171,16 @@ function resolveHookForToggle(
     );
   }
   if (opts?.requireEligible && !hook.requirementsSatisfied) {
-    throw new Error(`Hook "${hookName}" is not eligible (missing requirements)`);
+    const missing = formatHookMissingSummary(hook, 3);
+    const installHint = hook.install.length
+      ? ` Install options: ${summarizeStringEntries({
+          entries: hook.install.map((option) => option.label),
+          limit: 3,
+        })}.`
+      : "";
+    throw new Error(
+      `Hook "${hookName}" is not eligible; missing ${missing}.${installHint} Run \`${formatCliCommand(`openclaw hooks info ${hookName}`)}\` for details.`,
+    );
   }
   return hook;
 }
@@ -204,66 +209,6 @@ function buildConfigWithHookEnabled(params: {
   };
 }
 
-function formatHookStatus(hook: HookStatusEntry): string {
-  if (hook.loadable) {
-    return theme.success("✓ ready");
-  }
-  if (!hook.enabledByConfig) {
-    return theme.warn(decorativePrefix("⏸", "disabled"));
-  }
-  return theme.error(`✗ ${formatHookBlockedStatusReason(hook)}`);
-}
-
-function formatHookBlockedStatusReason(hook: HookStatusEntry): string {
-  return hook.blockedReason && hook.blockedReason !== "missing requirements"
-    ? hook.blockedReason
-    : "missing";
-}
-
-function formatHookInfoBlockedStatusReason(hook: HookStatusEntry): string {
-  const reason =
-    hook.blockedReason && hook.blockedReason !== "missing requirements"
-      ? hook.blockedReason
-      : "missing requirements";
-  return reason ? `${reason[0]?.toUpperCase() ?? ""}${reason.slice(1)}` : reason;
-}
-
-function formatHookName(hook: HookStatusEntry): string {
-  const emoji = hook.emoji ?? decorativeEmoji("🔗");
-  const name = theme.command(hook.name);
-  return emoji ? `${emoji} ${name}` : name;
-}
-
-function formatHookSource(hook: HookStatusEntry): string {
-  if (!hook.managedByPlugin) {
-    return hook.source;
-  }
-  return `plugin:${hook.pluginId ?? "unknown"}`;
-}
-
-function formatHookMissingSummary(hook: HookStatusEntry): string {
-  const missing: string[] = [];
-  if (hook.enabledByConfig && hook.blockedReason && hook.blockedReason !== "missing requirements") {
-    missing.push(hook.blockedReason);
-  }
-  if (hook.missing.bins.length > 0) {
-    missing.push(`bins: ${hook.missing.bins.join(", ")}`);
-  }
-  if (hook.missing.anyBins.length > 0) {
-    missing.push(`anyBins: ${hook.missing.anyBins.join(", ")}`);
-  }
-  if (hook.missing.env.length > 0) {
-    missing.push(`env: ${hook.missing.env.join(", ")}`);
-  }
-  if (hook.missing.config.length > 0) {
-    missing.push(`config: ${hook.missing.config.join(", ")}`);
-  }
-  if (hook.missing.os.length > 0) {
-    missing.push(`os: ${hook.missing.os.join(", ")}`);
-  }
-  return missing.join("; ");
-}
-
 function exitHooksCliWithError(err: unknown): never {
   rethrowExpectedCliError(err);
   defaultRuntime.error(`${theme.error("Error:")} ${formatErrorMessage(err)}`);
@@ -294,271 +239,6 @@ async function runOneShotHooksCliAction(action: () => Promise<number | void>): P
   // runCli finishes shared teardown and drains both output streams.
   requestExitAfterOneShotOutput(defaultRuntime, exitCode);
 }
-
-/**
- * Format the hooks list output
- */
-export function formatHooksList(report: HookStatusReport, opts: HooksListOptions): string {
-  const hooks = opts.eligible ? report.hooks.filter((h) => h.loadable) : report.hooks;
-
-  if (opts.json) {
-    const jsonReport = {
-      workspaceDir: report.workspaceDir,
-      managedHooksDir: report.managedHooksDir,
-      hooks: hooks.map((h) => ({
-        name: h.name,
-        description: h.description,
-        emoji: h.emoji,
-        eligible: h.loadable,
-        disabled: !h.enabledByConfig,
-        enabledByConfig: h.enabledByConfig,
-        requirementsSatisfied: h.requirementsSatisfied,
-        loadable: h.loadable,
-        blockedReason: h.blockedReason,
-        source: h.source,
-        pluginId: h.pluginId,
-        events: h.events,
-        unknownEvents: h.unknownEvents,
-        homepage: h.homepage,
-        missing: h.missing,
-        managedByPlugin: h.managedByPlugin,
-      })),
-    };
-    return JSON.stringify(jsonReport, null, 2);
-  }
-
-  if (hooks.length === 0) {
-    const message = opts.eligible
-      ? `No eligible hooks found. Run \`${formatCliCommand("openclaw hooks list")}\` to see all hooks.`
-      : "No hooks found.";
-    return message;
-  }
-
-  const eligible = hooks.filter((h) => h.loadable);
-  const tableWidth = getTerminalTableWidth();
-  const rows = hooks.map((hook) => {
-    const missing = formatHookMissingSummary(hook);
-    return {
-      Status: formatHookStatus(hook),
-      Hook: formatHookName(hook),
-      Description: theme.muted(hook.description),
-      Source: formatHookSource(hook),
-      Missing: missing ? theme.warn(missing) : "",
-    };
-  });
-
-  const columns = [
-    { key: "Status", header: "Status", minWidth: 10 },
-    { key: "Hook", header: "Hook", minWidth: 18, flex: true },
-    { key: "Description", header: "Description", minWidth: 24, flex: true },
-    { key: "Source", header: "Source", minWidth: 12, flex: true },
-  ];
-  if (opts.verbose) {
-    columns.push({ key: "Missing", header: "Missing", minWidth: 18, flex: true });
-  }
-
-  const lines: string[] = [];
-  lines.push(
-    `${theme.heading("Hooks")} ${theme.muted(`(${eligible.length}/${hooks.length} ready)`)}`,
-  );
-  lines.push(
-    renderTable({
-      width: tableWidth,
-      columns,
-      rows,
-    }).trimEnd(),
-  );
-  return lines.join("\n");
-}
-
-/**
- * Format detailed info for a single hook
- */
-export function formatHookInfo(
-  report: HookStatusReport,
-  hookName: string,
-  opts: HookInfoOptions,
-): string {
-  const hook = report.hooks.find((h) => h.name === hookName || h.hookKey === hookName);
-
-  if (!hook) {
-    if (opts.json) {
-      return JSON.stringify({ error: "not found", hook: hookName }, null, 2);
-    }
-    return `Hook "${hookName}" not found. Run \`${formatCliCommand("openclaw hooks list")}\` to see available hooks.`;
-  }
-
-  if (opts.json) {
-    return JSON.stringify(
-      {
-        ...hook,
-        eligible: hook.loadable,
-        disabled: !hook.enabledByConfig,
-      },
-      null,
-      2,
-    );
-  }
-
-  const lines: string[] = [];
-  const emoji = hook.emoji ?? decorativeEmoji("🔗");
-  const status = hook.loadable
-    ? theme.success("✓ Ready")
-    : !hook.enabledByConfig
-      ? theme.warn(decorativePrefix("⏸", "Disabled"))
-      : theme.error(`✗ ${formatHookInfoBlockedStatusReason(hook)}`);
-
-  lines.push(`${emoji ? `${emoji} ` : ""}${theme.heading(hook.name)} ${status}`);
-  lines.push("");
-  lines.push(hook.description);
-  lines.push("");
-
-  // Details
-  lines.push(theme.heading("Details:"));
-  if (hook.managedByPlugin) {
-    lines.push(`${theme.muted("  Source:")} ${hook.source} (${hook.pluginId ?? "unknown"})`);
-  } else {
-    lines.push(`${theme.muted("  Source:")} ${hook.source}`);
-  }
-  lines.push(`${theme.muted("  Path:")} ${shortenHomePath(hook.filePath)}`);
-  lines.push(`${theme.muted("  Handler:")} ${shortenHomePath(hook.handlerPath)}`);
-  if (hook.homepage) {
-    lines.push(`${theme.muted("  Homepage:")} ${hook.homepage}`);
-  }
-  if (hook.events.length > 0) {
-    lines.push(`${theme.muted("  Events:")} ${hook.events.join(", ")}`);
-  }
-  if (hook.unknownEvents.length > 0) {
-    lines.push(
-      theme.warn(
-        `  ⚠ Event${hook.unknownEvents.length === 1 ? "" : "s"} not emitted by core (likely typo): ${hook.unknownEvents.join(", ")}`,
-      ),
-    );
-  }
-  if (hook.managedByPlugin) {
-    lines.push(theme.muted("  Managed by plugin; enable/disable via hooks CLI not available."));
-  }
-  if (hook.blockedReason) {
-    lines.push(`${theme.muted("  Blocked reason:")} ${hook.blockedReason}`);
-  }
-
-  // Requirements
-  const hasRequirements =
-    hook.requirements.bins.length > 0 ||
-    hook.requirements.anyBins.length > 0 ||
-    hook.requirements.env.length > 0 ||
-    hook.requirements.config.length > 0 ||
-    hook.requirements.os.length > 0;
-
-  if (hasRequirements) {
-    lines.push("");
-    lines.push(theme.heading("Requirements:"));
-    if (hook.requirements.bins.length > 0) {
-      const binsStatus = hook.requirements.bins.map((bin) => {
-        const missing = hook.missing.bins.includes(bin);
-        return missing ? theme.error(`✗ ${bin}`) : theme.success(`✓ ${bin}`);
-      });
-      lines.push(`${theme.muted("  Binaries:")} ${binsStatus.join(", ")}`);
-    }
-    if (hook.requirements.anyBins.length > 0) {
-      const anyBinsStatus =
-        hook.missing.anyBins.length > 0
-          ? theme.error(`✗ (any of: ${hook.requirements.anyBins.join(", ")})`)
-          : theme.success(`✓ (any of: ${hook.requirements.anyBins.join(", ")})`);
-      lines.push(`${theme.muted("  Any binary:")} ${anyBinsStatus}`);
-    }
-    if (hook.requirements.env.length > 0) {
-      const envStatus = hook.requirements.env.map((env) => {
-        const missing = hook.missing.env.includes(env);
-        return missing ? theme.error(`✗ ${env}`) : theme.success(`✓ ${env}`);
-      });
-      lines.push(`${theme.muted("  Environment:")} ${envStatus.join(", ")}`);
-    }
-    if (hook.requirements.config.length > 0) {
-      const configStatus = hook.configChecks.map((check) => {
-        return check.satisfied ? theme.success(`✓ ${check.path}`) : theme.error(`✗ ${check.path}`);
-      });
-      lines.push(`${theme.muted("  Config:")} ${configStatus.join(", ")}`);
-    }
-    if (hook.requirements.os.length > 0) {
-      const osStatus =
-        hook.missing.os.length > 0
-          ? theme.error(`✗ (${hook.requirements.os.join(", ")})`)
-          : theme.success(`✓ (${hook.requirements.os.join(", ")})`);
-      lines.push(`${theme.muted("  OS:")} ${osStatus}`);
-    }
-  }
-
-  return lines.join("\n");
-}
-
-/**
- * Format check output
- */
-export function formatHooksCheck(report: HookStatusReport, opts: HooksCheckOptions): string {
-  if (opts.json) {
-    const eligible = report.hooks.filter((h) => h.loadable);
-    const notEligible = report.hooks.filter((h) => !h.loadable);
-    return JSON.stringify(
-      {
-        total: report.hooks.length,
-        eligible: eligible.length,
-        notEligible: notEligible.length,
-        hooks: {
-          eligible: eligible.map((h) => h.name),
-          notEligible: notEligible.map((h) => ({
-            name: h.name,
-            blockedReason: h.blockedReason,
-            missing: h.missing,
-          })),
-        },
-      },
-      null,
-      2,
-    );
-  }
-
-  const eligible = report.hooks.filter((h) => h.loadable);
-  const notEligible = report.hooks.filter((h) => !h.loadable);
-
-  const lines: string[] = [];
-  lines.push(theme.heading("Hooks Status"));
-  lines.push("");
-  lines.push(`${theme.muted("Total hooks:")} ${report.hooks.length}`);
-  lines.push(`${theme.success("Ready:")} ${eligible.length}`);
-  lines.push(`${theme.warn("Not ready:")} ${notEligible.length}`);
-
-  if (notEligible.length > 0) {
-    lines.push("");
-    lines.push(theme.heading("Hooks not ready:"));
-    for (const hook of notEligible) {
-      const reasons = [];
-      if (hook.blockedReason && hook.blockedReason !== "missing requirements") {
-        reasons.push(hook.blockedReason);
-      }
-      if (hook.missing.bins.length > 0) {
-        reasons.push(`bins: ${hook.missing.bins.join(", ")}`);
-      }
-      if (hook.missing.anyBins.length > 0) {
-        reasons.push(`anyBins: ${hook.missing.anyBins.join(", ")}`);
-      }
-      if (hook.missing.env.length > 0) {
-        reasons.push(`env: ${hook.missing.env.join(", ")}`);
-      }
-      if (hook.missing.config.length > 0) {
-        reasons.push(`config: ${hook.missing.config.join(", ")}`);
-      }
-      if (hook.missing.os.length > 0) {
-        reasons.push(`os: ${hook.missing.os.join(", ")}`);
-      }
-      const emoji = hook.emoji ?? decorativeEmoji("🔗");
-      lines.push(`  ${emoji ? `${emoji} ` : ""}${hook.name} - ${reasons.join("; ")}`);
-    }
-  }
-
-  return lines.join("\n");
-}
-
 async function enableHook(hookName: string, agentId?: string): Promise<void> {
   const snapshot = await readConfigFileSnapshot();
   const config = (snapshot.sourceConfig ?? snapshot.config) as OpenClawConfig;

From 1b998c0d84de7aeb46b1de550dcf682e84f4d53e Mon Sep 17 00:00:00 2001
From: Marvinthebored <marvin.assistant@lindsey.jp>
Date: Sat, 22 Aug 2026 03:12:58 +0800
Subject: [PATCH 075/124] fix: /restart restarts the gateway over and over
 instead of once (#127179)

The /restart command is dispatched from a durable channel ingress row. The
gateway begins its restart drain before that dispatch returns, so the row is
still claimed when root-work admission closes. The drain sees
GatewayDrainingError and releases the row without spending its retry budget
(#125918), which is correct for an ordinary message and wrong for a command
that caused the drain: the successor gateway claims the same row and runs
/restart again, forever. Every boot is clean, so the gateway looks healthy
throughout.

Adopt the ingress claim in the restart command handler before scheduling the
restart. The command is not idempotent, so losing the acknowledgement is better
than an unbounded restart loop. The drain's deferral branch is unchanged.

Co-authored-by: Marvinthebored <262704729+Marvinthebored@users.noreply.github.com>
---
 .../reply/commands-session-restart.test.ts    | 73 +++++++++++++++++++
 src/auto-reply/reply/commands-session.ts      |  7 ++
 2 files changed, 80 insertions(+)

diff --git a/src/auto-reply/reply/commands-session-restart.test.ts b/src/auto-reply/reply/commands-session-restart.test.ts
index 4e72991f6d17..658e15a61c8c 100644
--- a/src/auto-reply/reply/commands-session-restart.test.ts
+++ b/src/auto-reply/reply/commands-session-restart.test.ts
@@ -186,6 +186,79 @@ describe("handleRestartCommand", () => {
     }
   });
 
+  it("adopts the durable ingress claim before scheduling the restart", async () => {
+    const order: string[] = [];
+    mocks.scheduleGatewaySigusr1Restart.mockImplementationOnce((_opts) => {
+      order.push("schedule");
+      return { scheduled: true };
+    });
+    const handler = () => {};
+    process.on("SIGUSR1", handler);
+    try {
+      await handleRestartCommand(
+        restartCommandParams({
+          opts: {
+            turnAdoptionLifecycle: {
+              onAdopted: () => {
+                order.push("adopt");
+              },
+            },
+          } as HandleCommandsParams["opts"],
+        }),
+        true,
+      );
+    } finally {
+      process.removeListener("SIGUSR1", handler);
+    }
+
+    // Unadopted at restart => drain releases with recordAttempt:false and the
+    // successor replays /restart, restarting again forever.
+    expect(order).toEqual(["adopt", "schedule"]);
+  });
+
+  it("adopts the durable ingress claim before the fallback restart path", async () => {
+    const order: string[] = [];
+    mocks.triggerOpenClawRestart.mockImplementationOnce(() => {
+      order.push("trigger");
+      return { ok: true, method: "launchctl" };
+    });
+
+    await handleRestartCommand(
+      restartCommandParams({
+        opts: {
+          turnAdoptionLifecycle: {
+            onAdopted: () => {
+              order.push("adopt");
+            },
+          },
+        } as HandleCommandsParams["opts"],
+      }),
+      true,
+    );
+
+    expect(order).toEqual(["adopt", "trigger"]);
+  });
+
+  it("does not restart when ingress adoption was lost to another owner", async () => {
+    await expect(
+      handleRestartCommand(
+        restartCommandParams({
+          opts: {
+            turnAdoptionLifecycle: {
+              onAdopted: () => {
+                throw new Error("ingress adoption lost: guillotined");
+              },
+            },
+          } as HandleCommandsParams["opts"],
+        }),
+        true,
+      ),
+    ).rejects.toThrow("ingress adoption lost");
+
+    expect(mocks.triggerOpenClawRestart).not.toHaveBeenCalled();
+    expect(mocks.scheduleGatewaySigusr1Restart).not.toHaveBeenCalled();
+  });
+
   it("rejects authorized non-owner restart commands", async () => {
     const result = await handleRestartCommand(
       restartCommandParams({
diff --git a/src/auto-reply/reply/commands-session.ts b/src/auto-reply/reply/commands-session.ts
index d66f725a2aa3..4265edb7a24f 100644
--- a/src/auto-reply/reply/commands-session.ts
+++ b/src/auto-reply/reply/commands-session.ts
@@ -611,6 +611,13 @@ export const handleRestartCommand: CommandHandler = async (params, allowTextComm
   if (!isRestartEnabled(params.cfg)) {
     return sessionCommandReply("⚠️ /restart is disabled (commands.restart=false).");
   }
+  // Restart tears this process down before the dispatch that carries /restart can
+  // return, so the durable ingress claim would still be held when admission closes.
+  // The drain then releases it without spending retry budget and the successor
+  // replays /restart forever. Adopt here: the command is not idempotent, so losing
+  // the acknowledgement beats an unbounded restart loop. Adoption loss throws,
+  // which correctly aborts the restart because another owner holds the event.
+  await params.opts?.turnAdoptionLifecycle?.onAdopted();
   const hasSigusr1Listener = process.listenerCount("SIGUSR1") > 0;
   const sentinelPayload = buildRestartCommandSentinel(params);
   if (hasSigusr1Listener) {

From 90d1c43f5a185735891f5a0d30d3d0e0c7557f47 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 12:17:27 -0700
Subject: [PATCH 076/124] fix(ui): announce custom theme import results
 (#127380)

Amp-Thread-ID: https://ampcode.com/threads/T-01a021f4-b547-7788-a916-d4a94cbd3e3b

Co-authored-by: Amp <amp@ampcode.com>
---
 .../appearance-settings-defaults.e2e.test.ts  | 38 +++++++++++++++++++
 ui/src/pages/config/view-appearance.ts        |  3 ++
 2 files changed, 41 insertions(+)

diff --git a/ui/src/e2e/appearance-settings-defaults.e2e.test.ts b/ui/src/e2e/appearance-settings-defaults.e2e.test.ts
index 7d48a1aaa416..4749b276c1f4 100644
--- a/ui/src/e2e/appearance-settings-defaults.e2e.test.ts
+++ b/ui/src/e2e/appearance-settings-defaults.e2e.test.ts
@@ -600,6 +600,42 @@ suite.define(() => {
     }
   });
 
+  it("announces a failed custom-theme import", async () => {
+    await suite.withPage(
+      {
+        locale: "en-US",
+        serviceWorkers: "block",
+        viewport: { height: 900, width: 1440 },
+      },
+      async ({ page }) => {
+        const gateway = await installMockGateway(page, {
+          methodResponses: {
+            "config.get": configResponse({}, "custom-theme-invalid-1"),
+          },
+        });
+        await page.route("https://tweakcn.com/r/themes/network-failure", async (route) => {
+          await route.fulfill({ status: 503 });
+        });
+
+        const response = await page.goto(`${suite.server.baseUrl}settings/appearance`);
+        expect(response?.status()).toBe(200);
+        await waitForControlUiSettingsTakeover(page);
+        await gateway.waitForRequest("config.get");
+
+        await page.locator(".settings-theme-card--custom").click();
+        const importer = page.locator(".settings-theme-import");
+        await importer.locator("input").fill("https://tweakcn.com/themes/network-failure");
+        await importer.locator("button.primary").click();
+
+        await expect
+          .poll(async () => (await importer.getByRole("alert").textContent())?.trim())
+          .toBe("tweakcn import failed (503).");
+        expect(await gateway.getRequests("config.patch")).toHaveLength(0);
+        await captureViewport(page, "07-custom-theme-import-error-announced.png");
+      },
+    );
+  });
+
   it("keeps Clear authoritative after a delayed custom-theme replacement", async () => {
     const existingTheme = await importCustomThemeFromUrl(
       "existing",
@@ -693,6 +729,7 @@ suite.define(() => {
       await expect
         .poll(() => importer.locator(".settings-theme-import__message").textContent())
         .toContain("removed");
+      await expect.poll(() => importer.getByRole("status").count()).toBe(1);
       const afterDelayedResponse = await readThemeImportRaceState(page);
       expect(beforeReplace).toMatchObject({
         clawSelected: false,
@@ -797,6 +834,7 @@ suite.define(() => {
       await expect
         .poll(() => importer.locator(".settings-theme-import__message").textContent())
         .toContain("Imported");
+      await expect.poll(() => importer.getByRole("status").count()).toBe(1);
       expect(await gateway.getRequests("config.patch")).toHaveLength(0);
     } finally {
       releaseImport();
diff --git a/ui/src/pages/config/view-appearance.ts b/ui/src/pages/config/view-appearance.ts
index 04d3313914fc..8e849457d0c9 100644
--- a/ui/src/pages/config/view-appearance.ts
+++ b/ui/src/pages/config/view-appearance.ts
@@ -293,6 +293,9 @@ export function renderAppearanceSection(
                       ? html`<div
                           class="settings-theme-import__message settings-theme-import__message--${props
                             .customThemeImportMessage.kind}"
+                          role=${props.customThemeImportMessage.kind === "error"
+                            ? "alert"
+                            : "status"}
                         >
                           ${props.customThemeImportMessage.text}
                         </div>`

From 0b8596607208b1be7c963c701cbce8d45d565bf2 Mon Sep 17 00:00:00 2001
From: Josh Avant <830519+joshavant@users.noreply.github.com>
Date: Fri, 21 Aug 2026 12:20:21 -0700
Subject: [PATCH 077/124] fix gateway conversation route ownership (#126424)

---
 config/assertion-safety-baseline.txt          |   1 -
 ...-session-transcript-schema-baseline.sha256 |   2 +-
 docs/plugins/sdk-channel-plugins.md           |  32 +-
 docs/reference/database-schemas.md            |   6 +
 extensions/discord/src/channel.ts             |   3 +
 .../discord/src/conversation-identity.ts      |  12 +
 .../src/conversation-route-owner.test.ts      | 149 ++++++++
 .../discord/src/conversation-route-owner.ts   |  72 ++++
 .../src/monitor/agent-components.dispatch.ts  |   9 +
 .../src/monitor/conversation-binding-route.ts |  53 +++
 .../monitor/message-handler.context.test.ts   |  17 +
 .../src/monitor/message-handler.context.ts    |  19 +-
 .../message-handler.routing-preflight.ts      |  59 +--
 .../monitor/native-command-context.test.ts    |   8 +
 .../src/monitor/native-command-context.ts     |  11 +-
 .../src/monitor/route-resolution.test.ts      |  48 +++
 .../discord/src/monitor/route-resolution.ts   |  27 +-
 extensions/feishu/src/bot.test.ts             |   9 +
 extensions/feishu/src/bot.ts                  |   2 +
 extensions/feishu/src/channel.ts              |   1 +
 extensions/imessage/src/channel.ts            |   1 +
 .../src/monitor/inbound-processing.test.ts    |   1 +
 .../src/monitor/inbound-processing.ts         |   8 +
 extensions/matrix/src/channel.ts              |   3 +
 .../matrix/conversation-route-owner.test.ts   |  90 +++++
 .../src/matrix/conversation-route-owner.ts    |  43 +++
 extensions/matrix/src/matrix/monitor/route.ts |  18 +-
 .../src/mattermost/directory.test.ts          |  25 ++
 .../mattermost/src/mattermost/directory.ts    |  15 +-
 .../src/mattermost/monitor-event-plan.ts      |   4 +
 .../monitor.inbound-system-event.test.ts      |   5 +
 .../mattermost/slash-http.send-config.test.ts |  72 +++-
 .../mattermost/src/mattermost/slash-http.ts   |   4 +
 extensions/slack/src/channel.ts               |   2 +
 .../slack/src/conversation-binding-route.ts   | 153 ++++++++
 .../src/conversation-route-owner.test.ts      | 110 ++++++
 .../slack/src/conversation-route-owner.ts     | 107 ++++++
 .../message-handler/prepare-routing.ts        | 153 +-------
 .../monitor/message-handler/prepare.test.ts   |   2 +
 .../src/monitor/message-handler/prepare.ts    |   9 +
 .../slack/src/monitor/workspace-routing.ts    |   4 +-
 ...-message-context.dm-topic-threadid.test.ts |   2 +
 .../src/bot-message-context.session.ts        |  14 +
 ...bot-message-context.thread-binding.test.ts |   5 +-
 .../src/bot-message-context.typing.test.ts    |   8 +
 ...ot-native-command-dispatch.routing.test.ts |   4 +
 .../src/bot-native-command-dispatch.ts        |   2 +
 extensions/telegram/src/channel.ts            |   3 +
 .../src/conversation-route-owner.test.ts      | 133 +++++++
 .../telegram/src/conversation-route-owner.ts  |  90 +++++
 ...onversation-route.base-session-key.test.ts |   5 +-
 extensions/telegram/src/conversation-route.ts |  45 ++-
 package.json                                  |   4 +
 .../fixtures/packed-plugin-sdk-type-smoke.ts  |  17 +
 scripts/lib/plugin-sdk-doc-metadata.ts        |   3 +
 scripts/lib/plugin-sdk-entrypoints.json       |   1 +
 scripts/plugin-sdk-surface-report.mts         |   9 +-
 src/auto-reply/reply/commands-acp.test.ts     |   6 +
 src/auto-reply/reply/session.ts               |   6 +
 src/auto-reply/templating.ts                  |   4 +
 src/channels/direct-dm.test.ts                |   1 +
 src/channels/direct-dm.ts                     |  11 +-
 src/channels/feedback-reflection.test.ts      |   5 +-
 src/channels/feedback-reflection.ts           |   1 +
 src/channels/inbound-event/context.test.ts    |  12 +
 src/channels/inbound-event/context.ts         |   2 +
 src/channels/plugins/binding-routing.test.ts  |  28 ++
 src/channels/plugins/binding-routing.ts       |  43 ++-
 src/channels/plugins/types.adapters.ts        |   2 +
 src/channels/plugins/types.core.ts            |  26 ++
 src/config/sessions/conversation-identity.ts  |  10 +-
 .../sessions/conversation-registry.test.ts    | 181 +++++++++
 src/config/sessions/conversation-registry.ts  | 113 ++++--
 .../conversation-route-context.test.ts        |  57 +++
 .../sessions/conversation-route-context.ts    | 165 ++++++++
 .../conversation-route-fingerprint.test.ts    |  38 ++
 .../conversation-route-fingerprint.ts         |  48 +++
 .../session-accessor.lifecycle-types.ts       |   3 +
 src/config/sessions/session-accessor.reset.ts |   4 +
 .../session-accessor.sqlite-conversation.ts   | 155 +++++++-
 .../session-accessor.sqlite-entry-store.ts    |  10 +-
 .../sessions/session-accessor.sqlite-entry.ts |   2 +
 ...session-accessor.sqlite-lifecycle-state.ts |   1 +
 ...session-accessor.sqlite-lifecycle-types.ts |   2 +
 .../session-accessor.sqlite-projection.ts     |   2 +
 src/config/sessions/session-accessor.test.ts  |  18 +
 src/gateway/conversation-list.test.ts         | 122 ++++++
 src/gateway/conversation-list.ts              |  63 +++-
 .../conversation-route-ownership.test.ts      | 104 +++++
 src/gateway/conversation-route-ownership.ts   | 354 ++++++++++++++++++
 src/gateway/conversation-send.test.ts         | 127 ++++++-
 src/gateway/conversation-send.ts              |  36 +-
 src/gateway/conversation-turn.test.ts         | 179 ++++++++-
 src/gateway/conversation-turn.ts              |  68 +++-
 src/gateway/server-methods/conversations.ts   |  15 +-
 src/gateway/server-runtime-services.test.ts   |  54 ++-
 src/gateway/server-runtime-services.ts        |  35 +-
 src/infra/outbound/conversation-delivery.ts   |   4 +
 .../outbound/current-conversation-bindings.ts |  31 +-
 src/infra/outbound/deliver-contracts.ts       |   9 +
 src/infra/outbound/deliver-queue-execute.ts   |  19 +
 src/infra/outbound/deliver.test.ts            |  77 ++++
 src/infra/outbound/delivery-completion.ts     |   2 +
 src/infra/outbound/delivery-queue-recovery.ts |  16 +
 .../delivery-queue.reconnect-drain.test.ts    |  81 ++++
 .../outbound/delivery-queue.recovery.test.ts  |  10 +-
 .../outbound/message-action-contracts.ts      |   2 +
 src/infra/outbound/message-action-send.ts     |   1 +
 src/infra/outbound/message.ts                 |   3 +
 src/infra/outbound/outbound-send-service.ts   |   3 +
 src/infra/outbound/outbound-session.ts        |   3 +
 .../outbound/session-binding-service.test.ts  |  97 +++++
 src/infra/outbound/session-binding-service.ts |  23 ++
 ...sistence.historical-schema.test-support.ts |   6 +
 ...conversation-binding-inspection-runtime.ts |  20 +
 src/plugin-sdk/core.test.ts                   |  17 +
 src/plugin-sdk/delivery-queue-runtime.ts      |   6 +
 src/plugin-sdk/session-binding-runtime.ts     |   1 +
 src/plugins/channel-registry-state.types.ts   |   3 +
 src/state/openclaw-agent-db-schema-helpers.ts |   5 +-
 src/state/openclaw-agent-db-schema.ts         |   8 +-
 ...enclaw-agent-db-session-migrations.test.ts |  67 ++++
 .../openclaw-agent-db-session-migrations.ts   |  35 +-
 src/state/openclaw-agent-db.generated.d.ts    |   1 +
 src/state/openclaw-agent-db.test.ts           |   9 +
 src/state/openclaw-agent-schema.sql           |  13 +
 .../conversation-route-ownership.e2e.test.ts  | 337 +++++++++++++++++
 test/release-check.test.ts                    |   1 +
 128 files changed, 4406 insertions(+), 331 deletions(-)
 create mode 100644 extensions/discord/src/conversation-route-owner.test.ts
 create mode 100644 extensions/discord/src/conversation-route-owner.ts
 create mode 100644 extensions/discord/src/monitor/conversation-binding-route.ts
 create mode 100644 extensions/matrix/src/matrix/conversation-route-owner.test.ts
 create mode 100644 extensions/matrix/src/matrix/conversation-route-owner.ts
 create mode 100644 extensions/slack/src/conversation-binding-route.ts
 create mode 100644 extensions/slack/src/conversation-route-owner.test.ts
 create mode 100644 extensions/slack/src/conversation-route-owner.ts
 create mode 100644 extensions/telegram/src/conversation-route-owner.test.ts
 create mode 100644 extensions/telegram/src/conversation-route-owner.ts
 create mode 100644 src/config/sessions/conversation-route-context.test.ts
 create mode 100644 src/config/sessions/conversation-route-context.ts
 create mode 100644 src/config/sessions/conversation-route-fingerprint.test.ts
 create mode 100644 src/config/sessions/conversation-route-fingerprint.ts
 create mode 100644 src/gateway/conversation-route-ownership.test.ts
 create mode 100644 src/gateway/conversation-route-ownership.ts
 create mode 100644 src/plugin-sdk/conversation-binding-inspection-runtime.ts
 create mode 100644 test/e2e/qa-lab/runtime/conversation-route-ownership.e2e.test.ts

diff --git a/config/assertion-safety-baseline.txt b/config/assertion-safety-baseline.txt
index d0f22e2d1c9a..fbeb034a84ac 100644
--- a/config/assertion-safety-baseline.txt
+++ b/config/assertion-safety-baseline.txt
@@ -1200,7 +1200,6 @@ extensions/slack/src/monitor/message-handler/dispatch-helpers.ts	2
 extensions/slack/src/monitor/message-handler/dispatch-streaming.ts	6
 extensions/slack/src/monitor/message-handler/dispatch.ts	2
 extensions/slack/src/monitor/message-handler/prepare-dm-history.ts	1
-extensions/slack/src/monitor/message-handler/prepare-routing.ts	1
 extensions/slack/src/monitor/message-handler/prepare-thread-context.ts	1
 extensions/slack/src/monitor/message-handler/prepare.ts	3
 extensions/slack/src/monitor/message-handler/preview-finalize.ts	3
diff --git a/docs/.generated/sqlite-session-transcript-schema-baseline.sha256 b/docs/.generated/sqlite-session-transcript-schema-baseline.sha256
index edb97b8c7480..c9bb70248b94 100644
--- a/docs/.generated/sqlite-session-transcript-schema-baseline.sha256
+++ b/docs/.generated/sqlite-session-transcript-schema-baseline.sha256
@@ -1 +1 @@
-73cfbac3e2ef8a75d561165d9798c805e0a8c726c1bcd1c814c7cae777194b2b  sqlite-session-transcript-schema-baseline.sql
+fecbb8adccfa0be0b452f646d3bee8d5a17faeb2c2d8a2300fb75ef173c709cd  sqlite-session-transcript-schema-baseline.sql
diff --git a/docs/plugins/sdk-channel-plugins.md b/docs/plugins/sdk-channel-plugins.md
index 71090108eb79..b2cbfa03485d 100644
--- a/docs/plugins/sdk-channel-plugins.md
+++ b/docs/plugins/sdk-channel-plugins.md
@@ -350,11 +350,41 @@ normalizes numeric thread ids the same way core does, so prefer it over ad hoc
 should expose `messaging.resolveOutboundSessionRoute(...)` so core gets
 provider-native session and thread identity without parser shims.
 
+### Conversation route ownership
+
+Implement `messaging.resolveConversationRouteOwner(...)` when generic route
+matching cannot reproduce the channel's configured and runtime binding rules.
+The resolver receives the current config, account, and recorded conversation
+identity, including a delivery `target` when it differs from the routing peer.
+It must reuse the same precedence and provider identity grammar as inbound
+routing.
+
+Ownership inspection is synchronous and read-only. Do not refresh binding
+liveness, perform network requests, or infer missing provider facts. Return:
+
+- `{ kind: "agent", agentId }` for an agent-owned route.
+- `{ kind: "plugin", pluginId, fallbackAgentId }` for a plugin-owned runtime
+  binding. `fallbackAgentId` is the route used when that plugin has no active
+  inbound claim handler.
+- `{ kind: "unavailable" }` when authoritative owner state is temporarily
+  unavailable and the caller should retry.
+- `null` when the supplied identity is invalid or cannot be authorized.
+- `undefined` to delegate to core's generic owner resolution.
+
+Keep temporary unavailability distinct from `null`: an adapter restart is not
+proof that a previously bound conversation is unowned.
+Use `inspectConversationBinding(...)` from
+`openclaw/plugin-sdk/conversation-binding-inspection-runtime` when the resolver needs this
+available/unavailable distinction.
+
 ### Account-scoped conversation binding support
 
 Set `conversationBindings.supportsCurrentConversationBinding` when the channel
 supports generic current-conversation bindings. `createChatChannelPlugin(...)`
-sets this static capability to `true` by default.
+sets this static capability to `true` by default. Channels whose monitor owns a custom binding
+adapter must also set `bindingStore: "adapter"`; core then fails closed while
+that adapter is unavailable instead of reading or writing generic binding rows.
+Older `createManager`-only plugins retain the same adapter-owned behavior.
 
 If support differs by configured account, also implement
 `conversationBindings.isCurrentConversationBindingSupported({ accountId })`.
diff --git a/docs/reference/database-schemas.md b/docs/reference/database-schemas.md
index f9823357f554..1ed7512e56c0 100644
--- a/docs/reference/database-schemas.md
+++ b/docs/reference/database-schemas.md
@@ -38,6 +38,12 @@ operator's explicit offline-device abandonment decision so restart recovery
 cannot accidentally resume remote reconciliation. Older readers ignore the
 column and can reopen the same database safely.
 
+Conversation associations use the same rule for the nullable bare
+`route_context_json TEXT` column. The database-open repair ensures the column
+for updated binaries. Older readers ignore it and can reopen and update the
+same database safely; their association update invalidates context captured by
+a newer writer so it cannot be replayed after re-upgrade.
+
 Installing OpenClaw manually through npm bypasses the updater guard. Database open checks still refuse an incompatible build.
 
 ## Preflight a target release
diff --git a/extensions/discord/src/channel.ts b/extensions/discord/src/channel.ts
index 25b400a0b51d..abc37c80d27b 100644
--- a/extensions/discord/src/channel.ts
+++ b/extensions/discord/src/channel.ts
@@ -59,6 +59,7 @@ import {
   probeDiscordStatusAccount,
 } from "./channel.loaders.js";
 import { openDiscordCommandDeployHashStore } from "./command-deploy-store.js";
+import { inspectDiscordConversationRouteOwner } from "./conversation-route-owner.js";
 import { shouldSuppressLocalDiscordExecApprovalPrompt } from "./exec-approvals.js";
 import {
   resolveDiscordGroupRequireMention,
@@ -259,6 +260,7 @@ export const discordPlugin: ChannelPlugin<ResolvedDiscordAccount, DiscordProbe>
         ],
       },
       messaging: {
+        resolveConversationRouteOwner: inspectDiscordConversationRouteOwner,
         targetPrefixes: ["discord"],
         directTargetStyle: "user-prefixed",
         targetIdComparison: "lowercase",
@@ -424,6 +426,7 @@ export const discordPlugin: ChannelPlugin<ResolvedDiscordAccount, DiscordProbe>
       },
       conversationBindings: {
         supportsCurrentConversationBinding: true,
+        bindingStore: "adapter",
         defaultTopLevelPlacement,
         createManager: async ({ cfg, accountId }) =>
           (await loadDiscordThreadBindingsManagerModule()).createThreadBindingManager({
diff --git a/extensions/discord/src/conversation-identity.ts b/extensions/discord/src/conversation-identity.ts
index 74a23dd55dc7..301959d92511 100644
--- a/extensions/discord/src/conversation-identity.ts
+++ b/extensions/discord/src/conversation-identity.ts
@@ -34,6 +34,18 @@ export function resolveDiscordConversationIdentity(params: {
     : buildDiscordConversationIdentity("channel", params.channelId);
 }
 
+export function resolveDiscordRuntimeBindingConversationId(params: {
+  isDirectMessage: boolean;
+  isGroupDm: boolean;
+  userId?: string | null;
+  channelId: string;
+}): string {
+  if (params.isDirectMessage && !params.isGroupDm) {
+    return buildDiscordConversationIdentity("user", params.userId) ?? params.channelId;
+  }
+  return params.channelId;
+}
+
 export function resolveDiscordCurrentConversationIdentity(params: {
   chatType?: string | null;
   from?: string | null;
diff --git a/extensions/discord/src/conversation-route-owner.test.ts b/extensions/discord/src/conversation-route-owner.test.ts
new file mode 100644
index 000000000000..4d888076a16c
--- /dev/null
+++ b/extensions/discord/src/conversation-route-owner.test.ts
@@ -0,0 +1,149 @@
+import {
+  registerSessionBindingAdapter,
+  type SessionBindingAdapter,
+  testing as sessionBindingTesting,
+  unregisterSessionBindingAdapter,
+} from "openclaw/plugin-sdk/conversation-runtime";
+import {
+  createTestRegistry,
+  resetPluginRuntimeStateForTest,
+  setActivePluginRegistry,
+} from "openclaw/plugin-sdk/plugin-test-runtime";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { inspectDiscordConversationRouteOwner } from "./conversation-route-owner.js";
+
+describe("inspectDiscordConversationRouteOwner", () => {
+  let adapter: SessionBindingAdapter;
+
+  beforeEach(() => {
+    resetPluginRuntimeStateForTest();
+    setActivePluginRegistry(
+      createTestRegistry([
+        {
+          pluginId: "discord",
+          source: "test",
+          plugin: {
+            id: "discord",
+            meta: { aliases: [] },
+            conversationBindings: {
+              supportsCurrentConversationBinding: true,
+              createManager: () => ({ stop: () => undefined }),
+            },
+          },
+        },
+      ]),
+    );
+    sessionBindingTesting.resetSessionBindingAdaptersForTests();
+    adapter = {
+      channel: "discord",
+      accountId: "default",
+      listBySession: () => [],
+      resolveByConversation: () => null,
+    };
+    registerSessionBindingAdapter(adapter);
+  });
+
+  afterEach(() => {
+    resetPluginRuntimeStateForTest();
+    sessionBindingTesting.resetSessionBindingAdaptersForTests();
+  });
+
+  it("uses the direct-user runtime identity without touching liveness", () => {
+    const touch = vi.fn();
+    const resolveByConversation = vi.fn((conversation) => ({
+      bindingId: "binding-direct",
+      targetSessionKey: "agent:finance:bound",
+      targetKind: "session" as const,
+      conversation,
+      status: "active" as const,
+      boundAt: 1,
+    }));
+    registerSessionBindingAdapter({
+      channel: "discord",
+      accountId: "default",
+      listBySession: () => [],
+      resolveByConversation,
+      touch,
+    });
+
+    expect(
+      inspectDiscordConversationRouteOwner({
+        cfg: {},
+        accountId: "default",
+        conversation: { kind: "direct", peerId: "user-1", nativeChannelId: "dm-1" },
+      }),
+    ).toEqual({ kind: "agent", agentId: "finance" });
+    expect(resolveByConversation).toHaveBeenCalledWith(
+      expect.objectContaining({ conversationId: "user:user-1" }),
+    );
+    expect(touch).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    { kind: "group" as const, peerId: "group-dm-1" },
+    { kind: "channel" as const, peerId: "channel-1" },
+  ])("uses the native channel runtime identity for $kind conversations", ({ kind, peerId }) => {
+    const resolveByConversation = vi.fn(() => null);
+    registerSessionBindingAdapter({
+      channel: "discord",
+      accountId: "default",
+      listBySession: () => [],
+      resolveByConversation,
+    });
+
+    inspectDiscordConversationRouteOwner({
+      cfg: {},
+      accountId: "default",
+      conversation: { kind, peerId, nativeChannelId: peerId },
+    });
+
+    expect(resolveByConversation).toHaveBeenCalledWith(
+      expect.objectContaining({ conversationId: peerId }),
+    );
+  });
+
+  it("reports temporary adapter unavailability only while bindings are enabled", () => {
+    unregisterSessionBindingAdapter({ channel: "discord", accountId: "default", adapter });
+    const conversation = { kind: "channel" as const, peerId: "channel-1" };
+
+    expect(
+      inspectDiscordConversationRouteOwner({ cfg: {}, accountId: "default", conversation }),
+    ).toEqual({ kind: "unavailable" });
+    expect(
+      inspectDiscordConversationRouteOwner({
+        cfg: { channels: { discord: { threadBindings: { enabled: false } } } },
+        accountId: "default",
+        conversation,
+      }),
+    ).toEqual({ kind: "agent", agentId: "main" });
+  });
+
+  it("preserves explicit plugin ownership independently of the target session key", () => {
+    registerSessionBindingAdapter({
+      channel: "discord",
+      accountId: "default",
+      listBySession: () => [],
+      resolveByConversation: (conversation) => ({
+        bindingId: "binding-plugin",
+        targetSessionKey: "agent:review:looks-owned",
+        targetKind: "session",
+        conversation,
+        status: "active",
+        boundAt: 1,
+        metadata: {
+          pluginBindingOwner: "plugin",
+          pluginId: "review-plugin",
+          pluginRoot: "/plugins/review",
+        },
+      }),
+    });
+
+    expect(
+      inspectDiscordConversationRouteOwner({
+        cfg: {},
+        accountId: "default",
+        conversation: { kind: "channel", peerId: "channel-1" },
+      }),
+    ).toEqual({ kind: "plugin", pluginId: "review-plugin", fallbackAgentId: "main" });
+  });
+});
diff --git a/extensions/discord/src/conversation-route-owner.ts b/extensions/discord/src/conversation-route-owner.ts
new file mode 100644
index 000000000000..1772987b465b
--- /dev/null
+++ b/extensions/discord/src/conversation-route-owner.ts
@@ -0,0 +1,72 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import { resolveThreadBindingSpawnPolicy } from "openclaw/plugin-sdk/conversation-runtime";
+import { resolveDiscordRuntimeBindingConversationId } from "./conversation-identity.js";
+import { resolveDiscordConversationBindingRoute } from "./monitor/conversation-binding-route.js";
+import { resolveDiscordConversationRoute } from "./monitor/route-resolution.js";
+
+export function inspectDiscordConversationRouteOwner(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  conversation: {
+    kind: "direct" | "group" | "channel";
+    peerId: string;
+    threadId?: string;
+    nativeChannelId?: string;
+    context?: {
+      parentPeerId?: string;
+      guildId?: string;
+      memberRoleIds?: string[];
+    };
+  };
+}) {
+  const direct = params.conversation.kind === "direct";
+  const nativeConversationId = params.conversation.nativeChannelId ?? params.conversation.peerId;
+  const threadConversationId = direct ? undefined : params.conversation.threadId;
+  const runtimeConversationId =
+    threadConversationId ??
+    resolveDiscordRuntimeBindingConversationId({
+      isDirectMessage: direct,
+      isGroupDm: params.conversation.kind === "group",
+      userId: direct ? params.conversation.peerId : undefined,
+      channelId: nativeConversationId,
+    });
+  const route = resolveDiscordConversationRoute({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    guildId: params.conversation.context?.guildId,
+    memberRoleIds: params.conversation.context?.memberRoleIds,
+    peer: { kind: params.conversation.kind, id: params.conversation.peerId },
+    parentConversationId: params.conversation.context?.parentPeerId,
+  });
+  const { runtimeRoute, configuredRoute } = resolveDiscordConversationBindingRoute({
+    cfg: params.cfg,
+    route,
+    accountId: params.accountId,
+    runtimeConversationId,
+    configuredConversationId: threadConversationId ?? nativeConversationId,
+    parentConversationId: params.conversation.context?.parentPeerId,
+    touchBinding: false,
+  });
+  if (
+    !runtimeRoute.bindingOwnerAvailable &&
+    resolveThreadBindingSpawnPolicy({
+      cfg: params.cfg,
+      channel: "discord",
+      accountId: params.accountId,
+      kind: "subagent",
+    }).enabled
+  ) {
+    return { kind: "unavailable" as const };
+  }
+  if (runtimeRoute.pluginId) {
+    return {
+      kind: "plugin" as const,
+      pluginId: runtimeRoute.pluginId,
+      fallbackAgentId: route.agentId,
+    };
+  }
+  return {
+    kind: "agent" as const,
+    agentId: runtimeRoute.boundAgentId ?? configuredRoute?.boundAgentId ?? route.agentId,
+  };
+}
diff --git a/extensions/discord/src/monitor/agent-components.dispatch.ts b/extensions/discord/src/monitor/agent-components.dispatch.ts
index 069ab3e823ea..96124be017f1 100644
--- a/extensions/discord/src/monitor/agent-components.dispatch.ts
+++ b/extensions/discord/src/monitor/agent-components.dispatch.ts
@@ -36,6 +36,7 @@ import {
 } from "./inbound-context.js";
 import { buildDirectLabel, buildGuildLabel } from "./reply-context.js";
 import { deliverDiscordReply } from "./reply-delivery.js";
+import { buildDiscordConversationRouteContext } from "./route-resolution.js";
 
 const loadConversationRuntime = createLazyRuntimeModule(
   () => import("./agent-components.runtime.js"),
@@ -202,6 +203,14 @@ export async function dispatchDiscordComponentEvent(params: {
     SessionKey: sessionKey,
     AccountId: accountId,
     ChatType: chatType,
+    ...buildDiscordConversationRouteContext({
+      isDirectMessage: interactionCtx.isDirectMessage,
+      isGroupDm: interactionCtx.isGroupDm,
+      directUserId: interactionCtx.userId,
+      conversationId: interactionCtx.channelId,
+      isThread: channelCtx.isThread,
+      parentConversationId: channelCtx.parentId,
+    }),
     ConversationLabel: fromLabel,
     SenderName: senderName,
     SenderId: interactionCtx.userId,
diff --git a/extensions/discord/src/monitor/conversation-binding-route.ts b/extensions/discord/src/monitor/conversation-binding-route.ts
new file mode 100644
index 000000000000..bffc72693013
--- /dev/null
+++ b/extensions/discord/src/monitor/conversation-binding-route.ts
@@ -0,0 +1,53 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import {
+  resolveConfiguredBindingRoute,
+  resolveRuntimeConversationBindingRoute,
+} from "openclaw/plugin-sdk/conversation-binding-runtime";
+import type { ResolvedAgentRoute } from "openclaw/plugin-sdk/routing";
+import { logVerbose } from "openclaw/plugin-sdk/runtime-env";
+import { shouldIgnoreStaleDiscordRouteBinding } from "./route-resolution.js";
+
+export function resolveDiscordConversationBindingRoute(params: {
+  cfg: OpenClawConfig;
+  route: ResolvedAgentRoute;
+  accountId: string;
+  runtimeConversationId: string;
+  configuredConversationId: string;
+  parentConversationId?: string;
+  touchBinding?: boolean;
+}) {
+  let runtimeRoute = resolveRuntimeConversationBindingRoute({
+    route: params.route,
+    touchBinding: params.touchBinding,
+    conversation: {
+      channel: "discord",
+      accountId: params.accountId,
+      conversationId: params.runtimeConversationId,
+      parentConversationId: params.parentConversationId,
+    },
+  });
+  if (
+    shouldIgnoreStaleDiscordRouteBinding({
+      bindingRecord: runtimeRoute.bindingRecord,
+      route: params.route,
+    })
+  ) {
+    logVerbose(
+      `discord: ignoring stale route binding for conversation ${params.runtimeConversationId} (${runtimeRoute.bindingRecord?.targetSessionKey} -> ${params.route.sessionKey})`,
+    );
+    runtimeRoute = { bindingOwnerAvailable: true, bindingRecord: null, route: params.route };
+  }
+  const configuredRoute = runtimeRoute.bindingRecord
+    ? null
+    : resolveConfiguredBindingRoute({
+        cfg: params.cfg,
+        route: params.route,
+        conversation: {
+          channel: "discord",
+          accountId: params.accountId,
+          conversationId: params.configuredConversationId,
+          parentConversationId: params.parentConversationId,
+        },
+      });
+  return { runtimeRoute, configuredRoute };
+}
diff --git a/extensions/discord/src/monitor/message-handler.context.test.ts b/extensions/discord/src/monitor/message-handler.context.test.ts
index c8444f52572b..885d9ced50b8 100644
--- a/extensions/discord/src/monitor/message-handler.context.test.ts
+++ b/extensions/discord/src/monitor/message-handler.context.test.ts
@@ -31,6 +31,7 @@ describe("discord buildDiscordMessageProcessContext sender bot status", () => {
     }
 
     expect(result.ctxPayload.NativeChannelId).toBe(ctx.messageChannelId);
+    expect(result.ctxPayload.ConversationRoutePeerId).toBe(ctx.messageChannelId);
   });
 
   it("projects a cached conversation avatar into channel-owned context", async () => {
@@ -55,6 +56,22 @@ describe("discord buildDiscordMessageProcessContext sender bot status", () => {
     expect(result?.ctxPayload.GroupSpace).toBe("guild-id");
   });
 
+  it("records the source channel as the parent of an auto-threaded turn", async () => {
+    const ctx = await createBaseDiscordMessageContext({
+      channelConfig: { allowed: true, autoThread: true },
+      client: {
+        rest: {
+          get: async () => ({ thread: { id: "auto-thread-1" } }),
+        },
+      },
+    });
+
+    const result = await buildDiscordMessageProcessContext({ ctx, text: "hi", mediaList: [] });
+
+    expect(result?.ctxPayload.MessageThreadId).toBe("auto-thread-1");
+    expect(result?.ctxPayload.ThreadParentId).toBe("c1");
+  });
+
   it("forwards bot author status to ctxPayload.SenderIsBot", async () => {
     const ctx = await createBaseDiscordMessageContext({
       author: { id: "U1", username: "alice", discriminator: "0", globalName: "Alice", bot: true },
diff --git a/extensions/discord/src/monitor/message-handler.context.ts b/extensions/discord/src/monitor/message-handler.context.ts
index ff2d04d95de7..e5545c32a357 100644
--- a/extensions/discord/src/monitor/message-handler.context.ts
+++ b/extensions/discord/src/monitor/message-handler.context.ts
@@ -43,6 +43,7 @@ import {
   type DiscordMediaInfo,
 } from "./message-utils.js";
 import { buildDirectLabel, buildGuildLabel, resolveReplyContext } from "./reply-context.js";
+import { buildDiscordRoutePeer } from "./route-resolution.js";
 import { resolveDiscordAutoThreadReplyPlan, resolveDiscordThreadStarter } from "./threading.js";
 import {
   DISCORD_ATTACHMENT_IDLE_TIMEOUT_MS,
@@ -88,6 +89,7 @@ export async function buildDiscordMessageProcessContext(params: {
     messageChannelId,
     isGuildMessage,
     isDirectMessage,
+    isGroupDm,
     baseText,
     preflightAudioTranscript,
     threadChannel,
@@ -330,6 +332,11 @@ export async function buildDiscordMessageProcessContext(params: {
   const replyTarget = replyPlan.replyTarget;
   const replyReference = replyPlan.replyReference;
   const autoThreadContext = replyPlan.autoThreadContext;
+  const conversationParentId = threadChannel
+    ? threadParentId
+    : autoThreadContext
+      ? messageChannelId
+      : undefined;
 
   const effectiveFrom = isDirectMessage
     ? `discord:${author.id}`
@@ -372,7 +379,7 @@ export async function buildDiscordMessageProcessContext(params: {
       inboundEventKind: ctx.inboundEventKind,
     },
     {
-      parentId: threadChannel ? threadParentId : undefined,
+      parentId: conversationParentId,
       threadId: threadChannel?.id ?? autoThreadContext?.createdThreadId ?? undefined,
     },
   );
@@ -398,15 +405,21 @@ export async function buildDiscordMessageProcessContext(params: {
       isBot: author.bot && !sender.isPluralKit ? true : undefined,
     },
     conversation: {
-      kind: isDirectMessage ? "direct" : "channel",
+      kind: isGroupDm ? "group" : isDirectMessage ? "direct" : "channel",
       id: messageChannelId,
+      routePeer: buildDiscordRoutePeer({
+        isDirectMessage,
+        isGroupDm,
+        directUserId: author.id,
+        conversationId: messageChannelId,
+      }),
       nativeChannelId: messageChannelId,
       avatar: ctx.conversationAvatar,
       label: fromLabel,
       spaceId: isGuildMessage
         ? (guildInfo?.id ?? data.guild?.id ?? data.guild_id ?? guildSlug) || undefined
         : undefined,
-      parentId: threadChannel ? threadParentId : undefined,
+      parentId: conversationParentId,
       threadId: threadChannel?.id ?? autoThreadContext?.createdThreadId ?? undefined,
     },
     route: {
diff --git a/extensions/discord/src/monitor/message-handler.routing-preflight.ts b/extensions/discord/src/monitor/message-handler.routing-preflight.ts
index 858c82939f7b..9a26346f0f49 100644
--- a/extensions/discord/src/monitor/message-handler.routing-preflight.ts
+++ b/extensions/discord/src/monitor/message-handler.routing-preflight.ts
@@ -1,14 +1,13 @@
 import { createLazyRuntimeModule } from "openclaw/plugin-sdk/lazy-runtime";
 // Discord plugin module implements message handler.routing preflight behavior.
-import { logVerbose } from "openclaw/plugin-sdk/runtime-env";
-import { resolveDiscordConversationIdentity } from "../conversation-identity.js";
+import { resolveDiscordRuntimeBindingConversationId } from "../conversation-identity.js";
 import type { User } from "../internal/discord.js";
+import { resolveDiscordConversationBindingRoute } from "./conversation-binding-route.js";
 import type { DiscordMessagePreflightParams } from "./message-handler.preflight.types.js";
 import {
   buildDiscordRoutePeer,
   resolveDiscordConversationRoute,
   resolveDiscordEffectiveRoute,
-  shouldIgnoreStaleDiscordRouteBinding,
 } from "./route-resolution.js";
 
 const loadConversationRuntime = createLazyRuntimeModule(
@@ -38,49 +37,21 @@ export async function resolveDiscordPreflightRoute(params: {
     }),
     parentConversationId: params.earlyThreadParentId,
   });
-  const bindingConversationId = params.isDirectMessage
-    ? (resolveDiscordConversationIdentity({
-        isDirectMessage: true,
-        userId: params.author.id,
-      }) ?? `user:${params.author.id}`)
-    : params.messageChannelId;
-  let runtimeRoute = conversationRuntime.resolveRuntimeConversationBindingRoute({
-    route,
-    conversation: {
-      channel: "discord",
-      accountId: params.preflight.accountId,
-      conversationId: bindingConversationId,
-      parentConversationId: params.earlyThreadParentId,
-    },
+  const bindingConversationId = resolveDiscordRuntimeBindingConversationId({
+    isDirectMessage: params.isDirectMessage,
+    isGroupDm: params.isGroupDm,
+    userId: params.author.id,
+    channelId: params.messageChannelId,
+  });
+  const { runtimeRoute, configuredRoute } = resolveDiscordConversationBindingRoute({
+    cfg: params.preflight.cfg,
+    route,
+    accountId: params.preflight.accountId,
+    runtimeConversationId: bindingConversationId,
+    configuredConversationId: params.messageChannelId,
+    parentConversationId: params.earlyThreadParentId,
   });
-  if (
-    shouldIgnoreStaleDiscordRouteBinding({
-      bindingRecord: runtimeRoute.bindingRecord,
-      route,
-    })
-  ) {
-    logVerbose(
-      `discord: ignoring stale route binding for conversation ${bindingConversationId} (${runtimeRoute.bindingRecord?.targetSessionKey} -> ${route.sessionKey})`,
-    );
-    runtimeRoute = {
-      bindingRecord: null,
-      route,
-    };
-  }
   let threadBinding = runtimeRoute.bindingRecord ?? undefined;
-  const configuredRoute =
-    threadBinding == null
-      ? conversationRuntime.resolveConfiguredBindingRoute({
-          cfg: params.preflight.cfg,
-          route,
-          conversation: {
-            channel: "discord",
-            accountId: params.preflight.accountId,
-            conversationId: params.messageChannelId,
-            parentConversationId: params.earlyThreadParentId,
-          },
-        })
-      : null;
   const configuredBinding = configuredRoute?.bindingResolution ?? null;
   if (!threadBinding && configuredBinding) {
     threadBinding = configuredBinding.record;
diff --git a/extensions/discord/src/monitor/native-command-context.test.ts b/extensions/discord/src/monitor/native-command-context.test.ts
index 2afdca5d8568..41785eef85ca 100644
--- a/extensions/discord/src/monitor/native-command-context.test.ts
+++ b/extensions/discord/src/monitor/native-command-context.test.ts
@@ -35,6 +35,10 @@ describe("buildDiscordNativeCommandContext", () => {
     expect(ctx.ConversationLabel).toBe("Tester");
     expect(ctx.SessionKey).toBe("agent:codex:discord:slash:user-1");
     expect(ctx.CommandTargetSessionKey).toBe("agent:codex:discord:direct:user-1");
+    expect(ctx.ConversationRouteContextObserved).toBe(true);
+    expect(ctx.ConversationRoutePeerId).toBe("user-1");
+    expect(ctx.NativeChannelId).toBe("dm-1");
+    expect(ctx.InboundAccessAuthorized).toBe(true);
     expect(ctx.OriginatingTo).toBe("user:user-1");
     expect(ctx.ChannelPromptContext).toBeUndefined();
     expect(ctx.ChannelStructuredContext).toBeUndefined();
@@ -87,6 +91,10 @@ describe("buildDiscordNativeCommandContext", () => {
     expect(ctx.GroupSubject).toBe("Ops");
     expect(ctx.GroupSpace).toBe("guild-1");
     expect(ctx.MemberRoleIds).toEqual(["admin"]);
+    expect(ctx.ConversationRouteContextObserved).toBe(true);
+    expect(ctx.ConversationRoutePeerId).toBe("chan-1");
+    expect(ctx.NativeChannelId).toBe("chan-1");
+    expect(ctx.InboundAccessAuthorized).toBe(true);
     expect(ctx.GroupSystemPrompt).toBe("Use the runbook.");
     expect(ctx.OwnerAllowFrom).toEqual(["user-1"]);
     expect(ctx.MessageThreadId).toBe("chan-1");
diff --git a/extensions/discord/src/monitor/native-command-context.ts b/extensions/discord/src/monitor/native-command-context.ts
index 527147f7afb4..52099d4549a6 100644
--- a/extensions/discord/src/monitor/native-command-context.ts
+++ b/extensions/discord/src/monitor/native-command-context.ts
@@ -4,6 +4,7 @@ import { finalizeInboundContext } from "openclaw/plugin-sdk/reply-dispatch-runti
 import { resolveDiscordConversationIdentity } from "../conversation-identity.js";
 import type { DiscordChannelConfigResolved, DiscordGuildEntryResolved } from "./allow-list.js";
 import { buildDiscordInboundAccessContext } from "./inbound-context.js";
+import { buildDiscordConversationRouteContext } from "./route-resolution.js";
 
 type BuildDiscordNativeCommandContextParams = {
   prompt: string;
@@ -69,6 +70,14 @@ export function buildDiscordNativeCommandContext(params: BuildDiscordNativeComma
     CommandTargetSessionKey: params.commandTargetSessionKey,
     AccountId: params.accountId ?? undefined,
     ChatType: params.isDirectMessage ? "direct" : params.isGroupDm ? "group" : "channel",
+    ...buildDiscordConversationRouteContext({
+      isDirectMessage: params.isDirectMessage,
+      isGroupDm: params.isGroupDm,
+      directUserId: params.user.id,
+      conversationId: params.channelId,
+      isThread: params.isThreadChannel,
+      parentConversationId: params.threadParentId,
+    }),
     ConversationLabel: conversationLabel,
     GroupSubject: params.isGuild ? params.guildName : undefined,
     GroupSpace: params.isGuild
@@ -86,7 +95,6 @@ export function buildDiscordNativeCommandContext(params: BuildDiscordNativeComma
     Surface: "discord" as const,
     WasMentioned: true,
     MessageSid: params.interactionId,
-    MessageThreadId: params.isThreadChannel ? params.channelId : undefined,
     Timestamp: params.timestampMs ?? Date.now(),
     CommandAuthorized: params.commandAuthorized,
     CommandTurn: {
@@ -106,6 +114,5 @@ export function buildDiscordNativeCommandContext(params: BuildDiscordNativeComma
         userId: params.user.id,
         channelId: params.channelId,
       }) ?? (params.isDirectMessage ? `user:${params.user.id}` : `channel:${params.channelId}`),
-    ThreadParentId: params.isThreadChannel ? params.threadParentId : undefined,
   });
 }
diff --git a/extensions/discord/src/monitor/route-resolution.test.ts b/extensions/discord/src/monitor/route-resolution.test.ts
index 9612a10f6622..9300df98d987 100644
--- a/extensions/discord/src/monitor/route-resolution.test.ts
+++ b/extensions/discord/src/monitor/route-resolution.test.ts
@@ -3,6 +3,7 @@ import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
 import type { ResolvedAgentRoute } from "openclaw/plugin-sdk/routing";
 import { describe, expect, it } from "vitest";
 import {
+  buildDiscordConversationRouteContext,
   buildDiscordRoutePeer,
   resolveDiscordBoundConversationRoute,
   resolveDiscordConversationRoute,
@@ -46,6 +47,53 @@ describe("discord route resolution helpers", () => {
     });
   });
 
+  it("keeps a group DM keyed by its conversation instead of one sender", () => {
+    expect(
+      buildDiscordRoutePeer({
+        isDirectMessage: true,
+        isGroupDm: true,
+        directUserId: "user-1",
+        conversationId: "group-dm-1",
+      }),
+    ).toEqual({ kind: "group", id: "group-dm-1" });
+  });
+
+  it("records the direct routing peer separately from the native DM channel", () => {
+    expect(
+      buildDiscordConversationRouteContext({
+        isDirectMessage: true,
+        isGroupDm: false,
+        directUserId: "user-1",
+        conversationId: "dm-1",
+        isThread: false,
+      }),
+    ).toEqual({
+      ConversationRouteContextObserved: true,
+      ConversationRoutePeerId: "user-1",
+      NativeChannelId: "dm-1",
+      InboundAccessAuthorized: true,
+      MessageThreadId: undefined,
+      ThreadParentId: undefined,
+    });
+  });
+
+  it("records a thread and its routing parent", () => {
+    expect(
+      buildDiscordConversationRouteContext({
+        isDirectMessage: false,
+        isGroupDm: false,
+        conversationId: "thread-1",
+        isThread: true,
+        parentConversationId: "parent-1",
+      }),
+    ).toMatchObject({
+      ConversationRoutePeerId: "thread-1",
+      NativeChannelId: "thread-1",
+      MessageThreadId: "thread-1",
+      ThreadParentId: "parent-1",
+    });
+  });
+
   it("resolves bound session keys on top of the routed session", () => {
     const route: ResolvedAgentRoute = {
       agentId: "main",
diff --git a/extensions/discord/src/monitor/route-resolution.ts b/extensions/discord/src/monitor/route-resolution.ts
index 3556754a3f7e..110a8d8b6cfd 100644
--- a/extensions/discord/src/monitor/route-resolution.ts
+++ b/extensions/discord/src/monitor/route-resolution.ts
@@ -19,10 +19,29 @@ export function buildDiscordRoutePeer(params: {
   conversationId: string;
 }): RoutePeer {
   return {
-    kind: params.isDirectMessage ? "direct" : params.isGroupDm ? "group" : "channel",
-    id: params.isDirectMessage
-      ? params.directUserId?.trim() || params.conversationId
-      : params.conversationId,
+    kind: params.isGroupDm ? "group" : params.isDirectMessage ? "direct" : "channel",
+    id:
+      params.isDirectMessage && !params.isGroupDm
+        ? params.directUserId?.trim() || params.conversationId
+        : params.conversationId,
+  };
+}
+
+export function buildDiscordConversationRouteContext(params: {
+  isDirectMessage: boolean;
+  isGroupDm: boolean;
+  directUserId?: string | null;
+  conversationId: string;
+  isThread: boolean;
+  parentConversationId?: string;
+}) {
+  return {
+    ConversationRouteContextObserved: true as const,
+    ConversationRoutePeerId: buildDiscordRoutePeer(params).id,
+    NativeChannelId: params.conversationId,
+    InboundAccessAuthorized: true as const,
+    MessageThreadId: params.isThread ? params.conversationId : undefined,
+    ThreadParentId: params.isThread ? params.parentConversationId : undefined,
   };
 }
 
diff --git a/extensions/feishu/src/bot.test.ts b/extensions/feishu/src/bot.test.ts
index 914b0070b9c0..f6da4ff6c4f3 100644
--- a/extensions/feishu/src/bot.test.ts
+++ b/extensions/feishu/src/bot.test.ts
@@ -598,6 +598,9 @@ describe("handleFeishuMessage ACP routing", () => {
 
     expect(mockResolveConfiguredBindingRoute).toHaveBeenCalledTimes(1);
     expect(mockEnsureConfiguredBindingRouteReady).toHaveBeenCalledTimes(1);
+    expect(finalizeInboundContextMock).toHaveBeenCalledWith(
+      expect.objectContaining({ ConversationRoutePeerId: "ou_sender_1" }),
+    );
   });
 
   it("surfaces configured ACP initialization failures to the Feishu conversation", async () => {
@@ -687,6 +690,12 @@ describe("handleFeishuMessage ACP routing", () => {
     expect(conversationRef.channel).toBe("feishu");
     expect(conversationRef.conversationId).toBe("oc_group_chat:topic:om_topic_root");
     expect(mockTouchBinding).toHaveBeenCalledWith("default:oc_group_chat:topic:om_topic_root");
+    expect(finalizeInboundContextMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ConversationRoutePeerId: "oc_group_chat:topic:om_topic_root",
+        ThreadParentId: "oc_group_chat",
+      }),
+    );
   });
 
   it("records Feishu DM last-route updates on the resolved session", async () => {
diff --git a/extensions/feishu/src/bot.ts b/extensions/feishu/src/bot.ts
index ffe53aee5c79..c139f19935c4 100644
--- a/extensions/feishu/src/bot.ts
+++ b/extensions/feishu/src/bot.ts
@@ -1424,7 +1424,9 @@ export async function handleFeishuMessage(params: {
         conversation: {
           kind: isGroup ? "group" : "direct",
           id: ctx.chatId,
+          routePeer: { kind: isGroup ? "group" : "direct", id: peerId },
           nativeChannelId: ctx.chatId,
+          parentId: parentPeer?.id,
           label: isGroup && groupName && !isTopicSessionForThread ? groupName : undefined,
           threadId: ctx.rootId && isTopicSessionForThread ? ctx.rootId : undefined,
         },
diff --git a/extensions/feishu/src/channel.ts b/extensions/feishu/src/channel.ts
index 99267b707e73..8f3c121ccc22 100644
--- a/extensions/feishu/src/channel.ts
+++ b/extensions/feishu/src/channel.ts
@@ -993,6 +993,7 @@ export const feishuPlugin: ChannelPlugin<ResolvedFeishuAccount, FeishuProbeResul
         resolveToolPolicy: resolveFeishuGroupToolPolicy,
       },
       conversationBindings: {
+        bindingStore: "adapter",
         defaultTopLevelPlacement: "current",
         buildModelOverrideParentCandidates: ({ parentConversationId }) =>
           buildFeishuModelOverrideParentCandidates(parentConversationId),
diff --git a/extensions/imessage/src/channel.ts b/extensions/imessage/src/channel.ts
index 121587c03072..897e582c784a 100644
--- a/extensions/imessage/src/channel.ts
+++ b/extensions/imessage/src/channel.ts
@@ -318,6 +318,7 @@ export const imessagePlugin: ChannelPlugin<ResolvedIMessageAccount, IMessageProb
       doctor: imessageDoctor,
       conversationBindings: {
         supportsCurrentConversationBinding: true,
+        bindingStore: "adapter",
         createManager: ({ cfg, accountId }) =>
           createIMessageConversationBindingManager({
             cfg,
diff --git a/extensions/imessage/src/monitor/inbound-processing.test.ts b/extensions/imessage/src/monitor/inbound-processing.test.ts
index d6f2c15a8e0b..5ff0f14e1c9f 100644
--- a/extensions/imessage/src/monitor/inbound-processing.test.ts
+++ b/extensions/imessage/src/monitor/inbound-processing.test.ts
@@ -900,6 +900,7 @@ describe("resolveIMessageInboundDecision command auth", () => {
     });
 
     expect(ctxPayload.CommandAuthorized).toBe(true);
+    expect(ctxPayload.ConversationRoutePeerId).toBe("+15555550123");
     expect(ctxPayload.CommandSource).toBe("text");
     expect(ctxPayload.CommandTurn).toMatchObject({
       kind: "text-slash",
diff --git a/extensions/imessage/src/monitor/inbound-processing.ts b/extensions/imessage/src/monitor/inbound-processing.ts
index 984c847171c8..77ed7d280056 100644
--- a/extensions/imessage/src/monitor/inbound-processing.ts
+++ b/extensions/imessage/src/monitor/inbound-processing.ts
@@ -1039,6 +1039,14 @@ export async function buildIMessageInboundContext(params: {
     conversation: {
       kind: decision.isGroup ? "group" : "direct",
       id: chatId != null ? String(chatId) : decision.sender,
+      ...(decision.isGroup && chatId == null
+        ? {}
+        : {
+            routePeer: {
+              kind: decision.isGroup ? ("group" as const) : ("direct" as const),
+              id: decision.isGroup ? String(chatId) : decision.senderNormalized,
+            },
+          }),
       label: fromLabel,
     },
     route: {
diff --git a/extensions/matrix/src/channel.ts b/extensions/matrix/src/channel.ts
index fe2d42038d1b..6b5e4af221f2 100644
--- a/extensions/matrix/src/channel.ts
+++ b/extensions/matrix/src/channel.ts
@@ -58,6 +58,7 @@ import {
   resolveMatrixAccountConfig,
   type ResolvedMatrixAccount,
 } from "./matrix/accounts.js";
+import { resolveMatrixConversationRouteOwner } from "./matrix/conversation-route-owner.js";
 import { normalizeMatrixUserId } from "./matrix/monitor/allowlist.js";
 import type { MatrixProbe } from "./matrix/probe.js";
 import {
@@ -435,6 +436,7 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount, MatrixProbe> =
       },
       conversationBindings: {
         supportsCurrentConversationBinding: true,
+        bindingStore: "adapter",
         defaultTopLevelPlacement,
         setIdleTimeoutBySessionKey: ({ targetSessionKey, accountId, idleTimeoutMs }) =>
           setMatrixThreadBindingIdleTimeoutBySessionKey({
@@ -463,6 +465,7 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount, MatrixProbe> =
         resolveDeliveryTarget: ({ conversationId, parentConversationId }) =>
           resolveMatrixDeliveryTarget({ conversationId, parentConversationId }),
         resolveOutboundSessionRoute: (params) => resolveMatrixOutboundSessionRoute(params),
+        resolveConversationRouteOwner: resolveMatrixConversationRouteOwner,
         targetResolver: {
           looksLikeId: (raw) => {
             const trimmed = raw.trim();
diff --git a/extensions/matrix/src/matrix/conversation-route-owner.test.ts b/extensions/matrix/src/matrix/conversation-route-owner.test.ts
new file mode 100644
index 000000000000..a15efe7f26ce
--- /dev/null
+++ b/extensions/matrix/src/matrix/conversation-route-owner.test.ts
@@ -0,0 +1,90 @@
+import {
+  registerSessionBindingAdapter,
+  type SessionBindingAdapter,
+  testing as sessionBindingTesting,
+  unregisterSessionBindingAdapter,
+} from "openclaw/plugin-sdk/conversation-runtime";
+import {
+  createTestRegistry,
+  resetPluginRuntimeStateForTest,
+  setActivePluginRegistry,
+} from "openclaw/plugin-sdk/plugin-test-runtime";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { resolveMatrixConversationRouteOwner } from "./conversation-route-owner.js";
+
+describe("resolveMatrixConversationRouteOwner", () => {
+  let adapter: SessionBindingAdapter;
+
+  beforeEach(() => {
+    resetPluginRuntimeStateForTest();
+    setActivePluginRegistry(
+      createTestRegistry([
+        {
+          pluginId: "matrix",
+          source: "test",
+          plugin: {
+            id: "matrix",
+            meta: { aliases: [] },
+            conversationBindings: {
+              supportsCurrentConversationBinding: true,
+              createManager: () => ({ stop: () => undefined }),
+            },
+          },
+        },
+      ]),
+    );
+    sessionBindingTesting.resetSessionBindingAdaptersForTests();
+    adapter = {
+      channel: "matrix",
+      accountId: "default",
+      listBySession: () => [],
+      resolveByConversation: (conversation) => ({
+        bindingId: "binding-room",
+        targetSessionKey: "agent:finance:bound",
+        targetKind: "session",
+        conversation,
+        status: "active",
+        boundAt: 1,
+      }),
+    };
+    registerSessionBindingAdapter(adapter);
+  });
+
+  afterEach(() => {
+    resetPluginRuntimeStateForTest();
+    sessionBindingTesting.resetSessionBindingAdaptersForTests();
+  });
+
+  it("uses the native DM room and a channel peer's canonical room identity", () => {
+    expect(
+      resolveMatrixConversationRouteOwner({
+        cfg: {},
+        accountId: "default",
+        conversation: {
+          kind: "direct",
+          peerId: "@alice:example.org",
+          nativeChannelId: "!dm:example.org",
+        },
+      }),
+    ).toEqual({ kind: "agent", agentId: "finance" });
+    expect(
+      resolveMatrixConversationRouteOwner({
+        cfg: {},
+        accountId: "default",
+        conversation: { kind: "channel", peerId: "!room:example.org" },
+      }),
+    ).toEqual({ kind: "agent", agentId: "finance" });
+  });
+
+  it("reports temporary binding-store unavailability", () => {
+    unregisterSessionBindingAdapter({ channel: "matrix", accountId: "default", adapter });
+
+    expect(
+      resolveMatrixConversationRouteOwner({
+        cfg: {},
+        accountId: "default",
+        conversation: { kind: "channel", peerId: "!room:example.org" },
+      }),
+    ).toEqual({ kind: "unavailable" });
+  });
+});
diff --git a/extensions/matrix/src/matrix/conversation-route-owner.ts b/extensions/matrix/src/matrix/conversation-route-owner.ts
new file mode 100644
index 000000000000..d96ba2d99daa
--- /dev/null
+++ b/extensions/matrix/src/matrix/conversation-route-owner.ts
@@ -0,0 +1,43 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import { parseAgentSessionKey, resolveAgentRoute } from "openclaw/plugin-sdk/routing";
+import { resolveMatrixAccount } from "./accounts.js";
+import { resolveMatrixInboundRoute } from "./monitor/route.js";
+
+export function resolveMatrixConversationRouteOwner(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  conversation: {
+    kind: "direct" | "group" | "channel";
+    peerId: string;
+    threadId?: string;
+    nativeChannelId?: string;
+  };
+}) {
+  const { cfg, accountId, conversation } = params;
+  const roomId =
+    conversation.nativeChannelId?.trim() ||
+    (conversation.kind === "direct" ? "" : conversation.peerId.trim());
+  if (!roomId) {
+    return null;
+  }
+  const isDirectMessage = conversation.kind === "direct";
+  const result = resolveMatrixInboundRoute({
+    cfg,
+    accountId,
+    roomId,
+    senderId: conversation.peerId,
+    isDirectMessage,
+    dmSessionScope: resolveMatrixAccount({ cfg, accountId }).config.dm?.sessionScope,
+    threadId: conversation.threadId,
+    resolveAgentRoute,
+  });
+  if (!result.bindingOwnerAvailable) {
+    return { kind: "unavailable" as const };
+  }
+  if (result.runtimeBindingId && !parseAgentSessionKey(result.route.sessionKey)?.agentId) {
+    // Matrix's store cannot project plugin metadata. A non-agent runtime target therefore
+    // cannot authorize detached delivery through an inferred fallback owner.
+    return null;
+  }
+  return { kind: "agent" as const, agentId: result.route.agentId };
+}
diff --git a/extensions/matrix/src/matrix/monitor/route.ts b/extensions/matrix/src/matrix/monitor/route.ts
index 0c8d9c3d39bb..7cfa99edf2ca 100644
--- a/extensions/matrix/src/matrix/monitor/route.ts
+++ b/extensions/matrix/src/matrix/monitor/route.ts
@@ -6,7 +6,7 @@ import {
   deriveLastRoutePolicy,
   resolveAgentIdFromSessionKey,
 } from "openclaw/plugin-sdk/routing";
-import { getSessionBindingService } from "openclaw/plugin-sdk/session-binding-runtime";
+import { inspectSessionBindingByConversation } from "openclaw/plugin-sdk/session-binding-runtime";
 import type { CoreConfig } from "../../types.js";
 import { resolveMatrixThreadSessionKeys } from "./threads.js";
 
@@ -53,6 +53,7 @@ export function resolveMatrixInboundRoute(params: {
 }): {
   route: MatrixResolvedRoute;
   configuredBinding: ReturnType<typeof resolveConfiguredAcpBindingRecord>;
+  bindingOwnerAvailable: boolean;
   runtimeBindingId: string | null;
 } {
   const baseRoute = params.resolveAgentRoute({
@@ -74,13 +75,15 @@ export function resolveMatrixInboundRoute(params: {
   });
   const bindingConversationId = params.threadId ?? params.roomId;
   const bindingParentConversationId = params.threadId ? params.roomId : undefined;
-  const sessionBindingService = getSessionBindingService();
-  const runtimeBinding = sessionBindingService.resolveByConversation({
+  const bindingRef = {
     channel: "matrix",
     accountId: params.accountId,
     conversationId: bindingConversationId,
     parentConversationId: bindingParentConversationId,
-  });
+  };
+  const bindingInspection = inspectSessionBindingByConversation(bindingRef);
+  const runtimeBinding =
+    bindingInspection.status === "available" ? bindingInspection.binding : null;
   const boundSessionKey = runtimeBinding?.targetSessionKey?.trim();
 
   if (runtimeBinding && boundSessionKey) {
@@ -96,6 +99,7 @@ export function resolveMatrixInboundRoute(params: {
         matchedBy: "binding.channel",
       },
       configuredBinding: null,
+      bindingOwnerAvailable: true,
       runtimeBindingId: runtimeBinding.bindingId,
     };
   }
@@ -168,13 +172,15 @@ export function resolveMatrixInboundRoute(params: {
         }),
       },
       configuredBinding,
-      runtimeBindingId: null,
+      bindingOwnerAvailable: bindingInspection.status === "available",
+      runtimeBindingId: runtimeBinding?.bindingId ?? null,
     };
   }
 
   return {
     route: routeWithDmScope,
     configuredBinding,
-    runtimeBindingId: null,
+    bindingOwnerAvailable: bindingInspection.status === "available",
+    runtimeBindingId: runtimeBinding?.bindingId ?? null,
   };
 }
diff --git a/extensions/mattermost/src/mattermost/directory.test.ts b/extensions/mattermost/src/mattermost/directory.test.ts
index d67288a858d4..bb95cac1a775 100644
--- a/extensions/mattermost/src/mattermost/directory.test.ts
+++ b/extensions/mattermost/src/mattermost/directory.test.ts
@@ -62,6 +62,31 @@ describe("mattermost directory", () => {
     expect(createMattermostClientMock).toHaveBeenCalledOnce();
   });
 
+  it("uses only the requested account for scoped directory discovery", async () => {
+    const personalClient = { token: "token-personal", request: vi.fn().mockResolvedValue([]) };
+    listMattermostAccountIdsMock.mockReturnValue(["personal", "finance"]);
+    resolveMattermostAccountMock.mockImplementation(({ accountId }) => ({
+      enabled: true,
+      botToken: `token-${accountId}`,
+      baseUrl: "https://chat.example.com",
+    }));
+    createMattermostClientMock.mockReturnValue(personalClient);
+    fetchMattermostMeMock.mockResolvedValue({ id: "me-1" });
+
+    await expect(
+      listMattermostDirectoryGroups({
+        cfg: {} as never,
+        accountId: "personal",
+        runtime: {} as never,
+      }),
+    ).resolves.toEqual([]);
+    expect(resolveMattermostAccountMock).toHaveBeenCalledOnce();
+    expect(resolveMattermostAccountMock).toHaveBeenCalledWith({
+      cfg: {},
+      accountId: "personal",
+    });
+  });
+
   it("deduplicates channels across enabled accounts and skips failing accounts", async () => {
     const clientA = {
       token: "token-a",
diff --git a/extensions/mattermost/src/mattermost/directory.ts b/extensions/mattermost/src/mattermost/directory.ts
index 07914bfa4229..a762b139a4c1 100644
--- a/extensions/mattermost/src/mattermost/directory.ts
+++ b/extensions/mattermost/src/mattermost/directory.ts
@@ -35,17 +35,12 @@ function buildClient(params: {
   });
 }
 
-/**
- * Build clients from ALL enabled accounts (deduplicated by token).
- *
- * We always scan every account because:
- * - Private channels are only visible to bots that are members
- * - The requesting agent's account may have an expired/invalid token
- *
- * This means a single healthy bot token is enough for directory discovery.
- */
+/** Build the requested account client, or aggregate accounts for an explicitly unscoped lookup. */
 function buildClients(params: MattermostDirectoryParams): MattermostClient[] {
-  const accountIds = listMattermostAccountIds(params.cfg);
+  const requestedAccountId = params.accountId?.trim();
+  const accountIds = requestedAccountId
+    ? [requestedAccountId]
+    : listMattermostAccountIds(params.cfg);
   const seen = new Set<string>();
   const clients: MattermostClient[] = [];
   for (const id of accountIds) {
diff --git a/extensions/mattermost/src/mattermost/monitor-event-plan.ts b/extensions/mattermost/src/mattermost/monitor-event-plan.ts
index 6fa3a74927b1..cc3a45ace343 100644
--- a/extensions/mattermost/src/mattermost/monitor-event-plan.ts
+++ b/extensions/mattermost/src/mattermost/monitor-event-plan.ts
@@ -87,6 +87,8 @@ export async function buildMattermostEventPlan(
         ParentSessionKey: thread.parentSessionKey,
         AccountId: route.accountId,
         ChatType: kind,
+        ConversationRouteContextObserved: true,
+        ConversationRoutePeerId: kind === "direct" ? params.senderId : params.channelId,
         GroupChannel: channelName ? `#${channelName}` : undefined,
         GroupSpace: teamId,
         SenderId: params.senderId,
@@ -94,6 +96,8 @@ export async function buildMattermostEventPlan(
         Surface: "mattermost" as const,
         ReplyToId: thread.effectiveReplyToId,
         MessageThreadId: thread.effectiveReplyToId,
+        NativeChannelId: params.channelId,
+        InboundAccessAuthorized: true,
         OriginatingChannel: "mattermost" as const,
         OriginatingTo: to,
       }),
diff --git a/extensions/mattermost/src/mattermost/monitor.inbound-system-event.test.ts b/extensions/mattermost/src/mattermost/monitor.inbound-system-event.test.ts
index 5e1d3c50577d..560de63afd68 100644
--- a/extensions/mattermost/src/mattermost/monitor.inbound-system-event.test.ts
+++ b/extensions/mattermost/src/mattermost/monitor.inbound-system-event.test.ts
@@ -860,6 +860,11 @@ describe("mattermost inbound user posts", () => {
     expect(ctx?.BodyForAgent).toBe("hello from mattermost");
     expect(ctx?.ConversationLabel).toBe("Town Square id:chan-1");
     expect(ctx?.MessageSid).toBe("post-inbound-system-event-regular");
+    expect(ctx?.ConversationRouteContextObserved).toBe(true);
+    expect(ctx?.ConversationRoutePeerId).toBe("chan-1");
+    expect(ctx?.GroupSpace).toBe("team-1");
+    expect(ctx?.NativeChannelId).toBe("chan-1");
+    expect(ctx?.InboundAccessAuthorized).toBe(true);
     expect(ctx?.OriginatingChannel).toBe("mattermost");
     expect(ctx?.Provider).toBe("mattermost");
   });
diff --git a/extensions/mattermost/src/mattermost/slash-http.send-config.test.ts b/extensions/mattermost/src/mattermost/slash-http.send-config.test.ts
index d4f66b4c447f..826525683b3e 100644
--- a/extensions/mattermost/src/mattermost/slash-http.send-config.test.ts
+++ b/extensions/mattermost/src/mattermost/slash-http.send-config.test.ts
@@ -19,7 +19,7 @@ const mockState = vi.hoisted(() => ({
   })),
   resolveCommandText: vi.fn((_trigger: string, text: string) => text),
   buildModelsProviderData: vi.fn(async () => ({ providers: [], modelNames: new Map() })),
-  resolveMattermostModelPickerEntry: vi.fn(() => ({ kind: "summary" })),
+  resolveMattermostModelPickerEntry: vi.fn((): { kind: string } | null => ({ kind: "summary" })),
   authorizeMattermostCommandInvocation: vi.fn(() => ({
     ok: true,
     commandAuthorized: true,
@@ -49,6 +49,7 @@ const mockState = vi.hoisted(() => ({
     delete_at: 0,
   })),
   listMattermostCommands: vi.fn(async () => []),
+  dispatchInbound: vi.fn(async () => undefined),
 }));
 
 vi.mock("./runtime-api.js", () => {
@@ -83,7 +84,10 @@ vi.mock("../runtime.js", () => ({
       },
       text: {
         hasControlCommand: () => false,
+        resolveTextChunkLimit: () => 4000,
+        resolveMarkdownTableMode: () => "off",
       },
+      inbound: { dispatch: mockState.dispatchInbound },
       pairing: {
         readAllowFromStore: vi.fn(async () => []),
       },
@@ -123,6 +127,11 @@ vi.mock("./monitor-auth.js", () => ({
 }));
 
 vi.mock("./reply-delivery.js", () => ({
+  createMattermostReplyDeliveryBarrier: vi.fn(() => ({
+    markDeliverySettled: vi.fn(),
+    resolveTimeoutPolicy: vi.fn(),
+    trackDmChannelResolution: vi.fn(),
+  })),
   deliverMattermostReplyPayload: vi.fn(),
 }));
 
@@ -225,6 +234,7 @@ describe("slash-http cfg threading", () => {
     mockState.normalizeMattermostAllowList.mockClear();
     mockState.getMattermostCommand.mockClear();
     mockState.listMattermostCommands.mockClear();
+    mockState.dispatchInbound.mockClear();
     ({ createSlashCommandHttpHandler } = await import("./slash-http.js"));
   });
 
@@ -267,6 +277,66 @@ describe("slash-http cfg threading", () => {
     );
   });
 
+  it("keeps the slash team scope on direct conversations", async () => {
+    mockState.resolveMattermostModelPickerEntry.mockReturnValueOnce(null);
+    mockState.parseSlashCommandPayload.mockReturnValueOnce({
+      token: "valid-token",
+      command: "/oc_status",
+      text: "status",
+      channel_id: "dm-1",
+      user_id: "user-1",
+      user_name: "alice",
+      team_id: "team-1",
+    });
+    mockState.getMattermostCommand.mockResolvedValueOnce({
+      id: "cmd-status",
+      token: "valid-token",
+      team_id: "team-1",
+      trigger: "oc_status",
+      method: "P",
+      url: callbackUrlFixture,
+      delete_at: 0,
+    });
+    mockState.authorizeMattermostCommandInvocation.mockReturnValueOnce({
+      ok: true,
+      commandAuthorized: true,
+      channelInfo: { id: "dm-1", type: "D", name: "alice", display_name: "Alice" },
+      kind: "direct",
+      chatType: "direct",
+      channelName: "alice",
+      channelDisplay: "Alice",
+      roomLabel: "Alice",
+    });
+    const handler = createSlashCommandHttpHandler({
+      account: accountFixture,
+      cfg: {} as OpenClawConfig,
+      runtime: {} as RuntimeEnv,
+      registeredCommands: [
+        {
+          id: "cmd-status",
+          teamId: "team-1",
+          trigger: "oc_status",
+          token: "valid-token",
+          url: callbackUrlFixture,
+          managed: false,
+        },
+      ],
+    });
+
+    await handler(createRequest(), createResponse().res);
+
+    expect(mockState.dispatchInbound).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ctxPayload: expect.objectContaining({
+          ChatType: "direct",
+          ConversationRouteContextObserved: true,
+          ConversationRoutePeerId: "user-1",
+          GroupSpace: "team-1",
+        }),
+      }),
+    );
+  });
+
   it("rejects a callback when Mattermost reports a different current command token", async () => {
     mockState.parseSlashCommandPayload.mockReturnValueOnce({
       token: "old-token",
diff --git a/extensions/mattermost/src/mattermost/slash-http.ts b/extensions/mattermost/src/mattermost/slash-http.ts
index dec992722100..db53b80f9091 100644
--- a/extensions/mattermost/src/mattermost/slash-http.ts
+++ b/extensions/mattermost/src/mattermost/slash-http.ts
@@ -845,7 +845,10 @@ async function handleSlashCommandAsync(params: {
     SessionKey: route.sessionKey,
     AccountId: route.accountId,
     ChatType: chatType,
+    ConversationRouteContextObserved: true,
+    ConversationRoutePeerId: kind === "direct" ? senderId : channelId,
     ConversationLabel: fromLabel,
+    GroupSpace: teamId,
     GroupSubject: kind !== "direct" ? channelDisplay || roomLabel : undefined,
     SenderName: senderName,
     SenderId: senderId,
@@ -855,6 +858,7 @@ async function handleSlashCommandAsync(params: {
     Timestamp: Date.now(),
     WasMentioned: true,
     CommandAuthorized: commandAuthorized,
+    InboundAccessAuthorized: true,
     CommandSource: "native" as const,
     OriginatingChannel: "mattermost" as const,
     OriginatingTo: to,
diff --git a/extensions/slack/src/channel.ts b/extensions/slack/src/channel.ts
index a4b7c70a2cb2..302db982146b 100644
--- a/extensions/slack/src/channel.ts
+++ b/extensions/slack/src/channel.ts
@@ -56,6 +56,7 @@ import {
 } from "./channel-api.js";
 import { resolveSlackChannelType, resolveSlackConversationInfo } from "./channel-type.js";
 import { getSlackWriteClient } from "./client.js";
+import { inspectSlackConversationRouteOwner } from "./conversation-route-owner.js";
 import { assertSlackDetachedTargetAllowed } from "./detached-target-admission.js";
 import { formatSlackError } from "./errors.js";
 import { shouldSuppressLocalSlackExecApprovalPrompt } from "./exec-approvals.js";
@@ -667,6 +668,7 @@ export const slackPlugin: ChannelPlugin<ResolvedSlackAccount, SlackProbe> = crea
         isSlackWorkspaceInstallation(accountId),
     },
     messaging: {
+      resolveConversationRouteOwner: inspectSlackConversationRouteOwner,
       targetPrefixes: ["slack"],
       directTargetStyle: "user-prefixed",
       targetIdComparison: "lowercase",
diff --git a/extensions/slack/src/conversation-binding-route.ts b/extensions/slack/src/conversation-binding-route.ts
new file mode 100644
index 000000000000..d341c8ffddce
--- /dev/null
+++ b/extensions/slack/src/conversation-binding-route.ts
@@ -0,0 +1,153 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import {
+  resolveConfiguredBindingRoute,
+  resolveRuntimeConversationBindingRoute,
+  type RuntimeConversationBindingRouteResult,
+} from "openclaw/plugin-sdk/conversation-runtime";
+import type { resolveAgentRoute } from "openclaw/plugin-sdk/routing";
+import { parseSlackTarget, type SlackTargetKind } from "./targets.js";
+
+type SlackRouteBinding = NonNullable<OpenClawConfig["bindings"]>[number];
+type SlackRouteBindingPeer = NonNullable<SlackRouteBinding["match"]["peer"]>;
+
+const slackRouteBindingConfigCache = new WeakMap<
+  OpenClawConfig,
+  { bindingsRef: OpenClawConfig["bindings"]; normalizedCfg: OpenClawConfig }
+>();
+
+function slackTargetDefaultKindForPeer(kind: SlackRouteBindingPeer["kind"]): SlackTargetKind {
+  return kind === "direct" ? "user" : "channel";
+}
+
+function slackTargetKindMatchesPeer(
+  peerKind: SlackRouteBindingPeer["kind"],
+  targetKind: SlackTargetKind,
+): boolean {
+  if (targetKind === "user") {
+    return peerKind === "direct";
+  }
+  return peerKind === "channel" || peerKind === "group";
+}
+
+function normalizeSlackRouteBindingPeer(peer: SlackRouteBindingPeer): SlackRouteBindingPeer {
+  const rawId = peer.id.trim();
+  if (!rawId || rawId === "*") {
+    return peer;
+  }
+
+  const target = (() => {
+    try {
+      return parseSlackTarget(rawId, {
+        defaultKind: slackTargetDefaultKindForPeer(peer.kind),
+      });
+    } catch {
+      return undefined;
+    }
+  })();
+  if (!target || !slackTargetKindMatchesPeer(peer.kind, target.kind)) {
+    return peer;
+  }
+  const normalizedId = target.teamId
+    ? `team:${target.teamId}:${target.kind}:${target.id}`
+    : target.id;
+  return normalizedId === peer.id ? peer : { ...peer, id: normalizedId };
+}
+
+export function normalizeSlackRouteBindingConfig(cfg: OpenClawConfig): OpenClawConfig {
+  const bindings = cfg.bindings;
+  const cached = slackRouteBindingConfigCache.get(cfg);
+  if (cached && cached.bindingsRef === bindings) {
+    return cached.normalizedCfg;
+  }
+  if (!Array.isArray(bindings)) {
+    return cfg;
+  }
+
+  let changed = false;
+  const normalizedBindings: NonNullable<OpenClawConfig["bindings"]> = bindings.map((binding) => {
+    if (binding.type === "acp" || binding.match.channel.trim().toLowerCase() !== "slack") {
+      return binding;
+    }
+    const peer = binding.match.peer;
+    if (!peer) {
+      return binding;
+    }
+    const normalizedPeer = normalizeSlackRouteBindingPeer(peer);
+    if (normalizedPeer === peer) {
+      return binding;
+    }
+    changed = true;
+    return {
+      ...binding,
+      match: {
+        ...binding.match,
+        peer: normalizedPeer,
+      },
+    };
+  });
+
+  const normalizedCfg: OpenClawConfig = changed ? { ...cfg, bindings: normalizedBindings } : cfg;
+  slackRouteBindingConfigCache.set(cfg, { bindingsRef: bindings, normalizedCfg });
+  return normalizedCfg;
+}
+
+export function resolveSlackConversationBindingRoute(params: {
+  cfg: OpenClawConfig;
+  route: ReturnType<typeof resolveAgentRoute>;
+  accountId: string;
+  baseConversationId: string;
+  runtimeBindingThreadId?: string;
+  bindingsEnabled: boolean;
+  touchBinding?: boolean;
+}) {
+  const boundThreadRoute =
+    params.bindingsEnabled && params.runtimeBindingThreadId
+      ? resolveRuntimeConversationBindingRoute({
+          route: params.route,
+          touchBinding: params.touchBinding,
+          conversation: {
+            channel: "slack",
+            accountId: params.accountId,
+            conversationId: params.runtimeBindingThreadId,
+            parentConversationId: params.baseConversationId,
+          },
+        })
+      : null;
+  const runtimeRoute: RuntimeConversationBindingRouteResult = !params.bindingsEnabled
+    ? {
+        bindingOwnerAvailable: true,
+        route: params.route,
+        bindingRecord: null,
+        boundSessionKey: undefined,
+      }
+    : boundThreadRoute?.boundSessionKey || boundThreadRoute?.bindingRecord
+      ? boundThreadRoute
+      : resolveRuntimeConversationBindingRoute({
+          route: params.route,
+          touchBinding: params.touchBinding,
+          conversation: {
+            channel: "slack",
+            accountId: params.accountId,
+            conversationId: params.baseConversationId,
+          },
+        });
+  const configuredRoute =
+    params.bindingsEnabled && !runtimeRoute.boundSessionKey && !runtimeRoute.bindingRecord
+      ? resolveConfiguredBindingRoute({
+          cfg: params.cfg,
+          route: params.route,
+          conversation: {
+            channel: "slack",
+            accountId: params.accountId,
+            conversationId: params.baseConversationId,
+          },
+        })
+      : null;
+  return {
+    runtimeRoute,
+    configuredRoute,
+    route: runtimeRoute.boundSessionKey
+      ? runtimeRoute.route
+      : (configuredRoute?.route ?? params.route),
+  };
+}
diff --git a/extensions/slack/src/conversation-route-owner.test.ts b/extensions/slack/src/conversation-route-owner.test.ts
new file mode 100644
index 000000000000..796f08b86980
--- /dev/null
+++ b/extensions/slack/src/conversation-route-owner.test.ts
@@ -0,0 +1,110 @@
+import {
+  registerSessionBindingAdapter,
+  testing as sessionBindingTesting,
+} from "openclaw/plugin-sdk/conversation-runtime";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { inspectSlackConversationRouteOwner } from "./conversation-route-owner.js";
+import { registerSlackInstallationState } from "./installation-identity-state.js";
+
+describe("inspectSlackConversationRouteOwner", () => {
+  let releaseInstallation: (() => void) | undefined;
+
+  beforeEach(() => {
+    sessionBindingTesting.resetSessionBindingAdaptersForTests();
+    releaseInstallation = registerSlackInstallationState("default", "workspace").release;
+  });
+
+  afterEach(() => {
+    releaseInstallation?.();
+    sessionBindingTesting.resetSessionBindingAdaptersForTests();
+  });
+
+  it("checks the thread before its parent without touching liveness", () => {
+    const touch = vi.fn();
+    const resolveByConversation = vi.fn((conversation) =>
+      conversation.conversationId === "thread-1"
+        ? {
+            bindingId: "binding-thread",
+            targetSessionKey: "agent:finance:bound",
+            targetKind: "session" as const,
+            conversation,
+            status: "active" as const,
+            boundAt: 1,
+          }
+        : null,
+    );
+    registerSessionBindingAdapter({
+      channel: "slack",
+      accountId: "default",
+      listBySession: () => [],
+      resolveByConversation,
+      touch,
+    });
+
+    expect(
+      inspectSlackConversationRouteOwner({
+        cfg: {},
+        accountId: "default",
+        conversation: { kind: "channel", peerId: "channel-1", threadId: "thread-1" },
+      }),
+    ).toEqual({ kind: "agent", agentId: "finance" });
+    expect(resolveByConversation).toHaveBeenCalledWith({
+      channel: "slack",
+      accountId: "default",
+      conversationId: "thread-1",
+      parentConversationId: "channel-1",
+    });
+    expect(touch).not.toHaveBeenCalled();
+  });
+
+  it("distinguishes degraded identity from a qualified target conflict", () => {
+    releaseInstallation?.();
+    const installation = registerSlackInstallationState("default", "degraded");
+    releaseInstallation = installation.release;
+
+    expect(
+      inspectSlackConversationRouteOwner({
+        cfg: {},
+        accountId: "default",
+        conversation: { kind: "channel", peerId: "C456" },
+      }),
+    ).toEqual({ kind: "unavailable" });
+    installation.update("workspace");
+    expect(
+      inspectSlackConversationRouteOwner({
+        cfg: {},
+        accountId: "default",
+        conversation: { kind: "channel", peerId: "team:T123:channel:C456" },
+      }),
+    ).toBeNull();
+  });
+
+  it("fails closed when workspace identity is released during binding inspection", () => {
+    registerSessionBindingAdapter({
+      channel: "slack",
+      accountId: "default",
+      listBySession: () => [],
+      resolveByConversation: (conversation) => ({
+        bindingId: "binding-channel",
+        targetSessionKey: "agent:finance:bound",
+        targetKind: "session",
+        conversation,
+        status: "active",
+        boundAt: 1,
+      }),
+    });
+    const input = {
+      cfg: {},
+      accountId: "default",
+      conversation: { kind: "channel" as const, peerId: "C456" },
+    };
+
+    expect(inspectSlackConversationRouteOwner(input)).toEqual({
+      kind: "agent",
+      agentId: "finance",
+    });
+    releaseInstallation?.();
+    releaseInstallation = undefined;
+    expect(inspectSlackConversationRouteOwner(input)).toEqual({ kind: "unavailable" });
+  });
+});
diff --git a/extensions/slack/src/conversation-route-owner.ts b/extensions/slack/src/conversation-route-owner.ts
new file mode 100644
index 000000000000..429d3317697c
--- /dev/null
+++ b/extensions/slack/src/conversation-route-owner.ts
@@ -0,0 +1,107 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import { resolveAgentRoute } from "openclaw/plugin-sdk/routing";
+import {
+  normalizeSlackRouteBindingConfig,
+  resolveSlackConversationBindingRoute,
+} from "./conversation-binding-route.js";
+import { getSlackInstallationKind } from "./installation-identity-state.js";
+import {
+  qualifySlackConversationId,
+  qualifySlackRoutePeerId,
+} from "./monitor/workspace-routing.js";
+import { parseSlackTarget } from "./targets.js";
+
+export function inspectSlackConversationRouteOwner(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  conversation: {
+    kind: "direct" | "group" | "channel";
+    peerId: string;
+    threadId?: string;
+    nativeChannelId?: string;
+    context?: { teamId?: string };
+  };
+}) {
+  const installationKind = getSlackInstallationKind(params.accountId);
+  const direct = params.conversation.kind === "direct";
+  const target = parseSlackTarget(params.conversation.peerId, {
+    defaultKind: direct ? "user" : "channel",
+  });
+  if (!target || target.kind !== (direct ? "user" : "channel")) {
+    return null;
+  }
+  // Qualified targets remain durable Enterprise evidence after monitor teardown. Only an
+  // unqualified target is ambiguous while installation identity is temporarily degraded.
+  const targetIsEnterprise = Boolean(target.teamId);
+  if (!targetIsEnterprise && (installationKind === "degraded" || !installationKind)) {
+    return { kind: "unavailable" as const };
+  }
+  if (targetIsEnterprise && installationKind === "workspace") {
+    return null;
+  }
+  const contextTeamId = params.conversation.context?.teamId?.trim();
+  if (
+    contextTeamId &&
+    target.teamId &&
+    contextTeamId.toLowerCase() !== target.teamId.toLowerCase()
+  ) {
+    return null;
+  }
+  const teamId = contextTeamId ?? target.teamId;
+  if (
+    !direct &&
+    params.conversation.nativeChannelId &&
+    params.conversation.nativeChannelId.toLowerCase() !== target.id.toLowerCase()
+  ) {
+    return null;
+  }
+  const enterpriseRoute = installationKind === "enterprise" || targetIsEnterprise;
+  if (enterpriseRoute && !teamId) {
+    return null;
+  }
+  const enterpriseScope = enterpriseRoute && teamId ? { teamId } : undefined;
+  const route = resolveAgentRoute({
+    cfg: normalizeSlackRouteBindingConfig(params.cfg),
+    channel: "slack",
+    accountId: params.accountId,
+    teamId,
+    peer: {
+      kind: params.conversation.kind,
+      id: qualifySlackRoutePeerId({
+        id: target.id,
+        kind: direct ? "user" : "channel",
+        eventScope: enterpriseScope,
+      }),
+    },
+  });
+  const baseConversationId = qualifySlackConversationId(
+    direct ? `user:${target.id}` : target.id,
+    enterpriseScope,
+  );
+  const bindingRoute = resolveSlackConversationBindingRoute({
+    cfg: params.cfg,
+    route,
+    accountId: params.accountId,
+    baseConversationId,
+    runtimeBindingThreadId: params.conversation.threadId,
+    bindingsEnabled: !enterpriseRoute,
+    touchBinding: false,
+  });
+  if (!bindingRoute.runtimeRoute.bindingOwnerAvailable) {
+    return { kind: "unavailable" as const };
+  }
+  if (bindingRoute.runtimeRoute.pluginId) {
+    return {
+      kind: "plugin" as const,
+      pluginId: bindingRoute.runtimeRoute.pluginId,
+      fallbackAgentId: route.agentId,
+    };
+  }
+  return {
+    kind: "agent" as const,
+    agentId:
+      bindingRoute.runtimeRoute.boundAgentId ??
+      bindingRoute.configuredRoute?.boundAgentId ??
+      route.agentId,
+  };
+}
diff --git a/extensions/slack/src/monitor/message-handler/prepare-routing.ts b/extensions/slack/src/monitor/message-handler/prepare-routing.ts
index d4fd57295279..3fba0ec7c6ae 100644
--- a/extensions/slack/src/monitor/message-handler/prepare-routing.ts
+++ b/extensions/slack/src/monitor/message-handler/prepare-routing.ts
@@ -1,15 +1,16 @@
 // Slack plugin module implements prepare routing behavior.
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
-import {
-  resolveConfiguredBindingRoute,
-  resolveRuntimeConversationBindingRoute,
-  type ConfiguredBindingRouteResult,
-  type RuntimeConversationBindingRouteResult,
+import type {
+  ConfiguredBindingRouteResult,
+  RuntimeConversationBindingRouteResult,
 } from "openclaw/plugin-sdk/conversation-runtime";
 import { resolveAgentRoute, resolveThreadSessionKeys } from "openclaw/plugin-sdk/routing";
 import { resolveSlackReplyToMode } from "../../account-reply-mode.js";
 import type { ResolvedSlackAccount } from "../../accounts.js";
-import { parseSlackTarget, type SlackTargetKind } from "../../targets.js";
+import {
+  normalizeSlackRouteBindingConfig,
+  resolveSlackConversationBindingRoute,
+} from "../../conversation-binding-route.js";
 import { resolveSlackThreadContext } from "../../threading.js";
 import type { SlackMessageEvent } from "../../types.js";
 import type { SlackChannelConfigResolved } from "../channel-config.js";
@@ -43,92 +44,6 @@ type SlackRoutingContext = {
   historyKey: string;
 };
 
-type SlackRouteBinding = NonNullable<OpenClawConfig["bindings"]>[number];
-type SlackRouteBindingPeer = NonNullable<SlackRouteBinding["match"]["peer"]>;
-
-const slackRouteBindingConfigCache = new WeakMap<
-  OpenClawConfig,
-  { bindingsRef: OpenClawConfig["bindings"]; normalizedCfg: OpenClawConfig }
->();
-
-function slackTargetDefaultKindForPeer(kind: SlackRouteBindingPeer["kind"]): SlackTargetKind {
-  return kind === "direct" ? "user" : "channel";
-}
-
-function slackTargetKindMatchesPeer(
-  peerKind: SlackRouteBindingPeer["kind"],
-  targetKind: SlackTargetKind,
-): boolean {
-  if (targetKind === "user") {
-    return peerKind === "direct";
-  }
-  return peerKind === "channel" || peerKind === "group";
-}
-
-function normalizeSlackRouteBindingPeer(peer: SlackRouteBindingPeer): SlackRouteBindingPeer {
-  const rawId = peer.id.trim();
-  if (!rawId || rawId === "*") {
-    return peer;
-  }
-
-  const target = (() => {
-    try {
-      return parseSlackTarget(rawId, {
-        defaultKind: slackTargetDefaultKindForPeer(peer.kind),
-      });
-    } catch {
-      return undefined;
-    }
-  })();
-  if (!target || !slackTargetKindMatchesPeer(peer.kind, target.kind)) {
-    return peer;
-  }
-  const normalizedId = target.teamId
-    ? `team:${target.teamId}:${target.kind}:${target.id}`
-    : target.id;
-  return normalizedId === peer.id ? peer : { ...peer, id: normalizedId };
-}
-
-function normalizeSlackRouteBindingConfig(cfg: OpenClawConfig): OpenClawConfig {
-  const bindings = cfg.bindings;
-  const cached = slackRouteBindingConfigCache.get(cfg);
-  if (cached && cached.bindingsRef === bindings) {
-    return cached.normalizedCfg;
-  }
-  if (!Array.isArray(bindings)) {
-    return cfg;
-  }
-
-  let changed = false;
-  const normalizedBindings = bindings.map((binding) => {
-    if (binding.type === "acp" || binding.match.channel.trim().toLowerCase() !== "slack") {
-      return binding;
-    }
-    const peer = binding.match.peer;
-    if (!peer) {
-      return binding;
-    }
-    const normalizedPeer = normalizeSlackRouteBindingPeer(peer);
-    if (normalizedPeer === peer) {
-      return binding;
-    }
-    changed = true;
-    return {
-      ...binding,
-      match: {
-        ...binding.match,
-        peer: normalizedPeer,
-      },
-    };
-  });
-
-  const normalizedCfg = changed
-    ? ({ ...cfg, bindings: normalizedBindings } as OpenClawConfig)
-    : cfg;
-  slackRouteBindingConfigCache.set(cfg, { bindingsRef: bindings, normalizedCfg });
-  return normalizedCfg;
-}
-
 function resolveSlackBaseConversationId(params: {
   message: SlackMessageEvent;
   isDirectMessage: boolean;
@@ -259,48 +174,18 @@ export function resolveSlackRoutingContext(params: {
   });
   const runtimeBindingThreadId =
     routedThreadId ?? (isDirectMessage && isThreadReply ? threadTs : undefined);
-  const boundThreadRoute =
-    !eventScope && runtimeBindingThreadId
-      ? resolveRuntimeConversationBindingRoute({
-          route,
-          conversation: {
-            channel: "slack",
-            accountId: account.accountId,
-            conversationId: runtimeBindingThreadId,
-            parentConversationId: baseConversationId,
-          },
-        })
-      : null;
-  const runtimeRoute = eventScope
-    ? { route, bindingRecord: null, boundSessionKey: undefined }
-    : boundThreadRoute?.boundSessionKey || boundThreadRoute?.bindingRecord
-      ? boundThreadRoute
-      : resolveRuntimeConversationBindingRoute({
-          route,
-          conversation: {
-            channel: "slack",
-            accountId: account.accountId,
-            conversationId: baseConversationId,
-          },
-        });
-  let configuredBinding: ConfiguredBindingRouteResult["bindingResolution"] = null;
-  let configuredBindingSessionKey = "";
-  if (runtimeRoute.boundSessionKey || runtimeRoute.bindingRecord) {
-    route = runtimeRoute.route;
-  } else if (!eventScope) {
-    const configuredRoute = resolveConfiguredBindingRoute({
-      cfg: ctx.cfg,
-      route,
-      conversation: {
-        channel: "slack",
-        accountId: account.accountId,
-        conversationId: baseConversationId,
-      },
-    });
-    configuredBinding = configuredRoute.bindingResolution;
-    configuredBindingSessionKey = configuredRoute.boundSessionKey ?? "";
-    route = configuredRoute.route;
-  }
+  const bindingRoute = resolveSlackConversationBindingRoute({
+    cfg: ctx.cfg,
+    route,
+    accountId: account.accountId,
+    baseConversationId,
+    runtimeBindingThreadId,
+    bindingsEnabled: !eventScope,
+  });
+  const runtimeRoute = bindingRoute.runtimeRoute;
+  const configuredBinding = bindingRoute.configuredRoute?.bindingResolution ?? null;
+  const configuredBindingSessionKey = bindingRoute.configuredRoute?.boundSessionKey ?? "";
+  route = bindingRoute.route;
   const threadKeys =
     runtimeRoute.boundSessionKey || configuredBindingSessionKey
       ? { sessionKey: route.sessionKey, parentSessionKey: undefined }
diff --git a/extensions/slack/src/monitor/message-handler/prepare.test.ts b/extensions/slack/src/monitor/message-handler/prepare.test.ts
index 8793e4cd2575..0037148a7d90 100644
--- a/extensions/slack/src/monitor/message-handler/prepare.test.ts
+++ b/extensions/slack/src/monitor/message-handler/prepare.test.ts
@@ -505,6 +505,8 @@ describe("slack prepareSlackMessage inbound contract", () => {
 
     assertPrepared(prepared, "org-wide Slack DM");
     expect(prepared.ctxPayload.GroupSpace).toBe("T123ENTERPRISE");
+    expect(prepared.ctxPayload.ConversationRouteContextObserved).toBe(true);
+    expect(prepared.ctxPayload.ConversationRoutePeerId).toBe("team:T123ENTERPRISE:user:U123");
     expect(prepared.ctxPayload.To).toBe("team:T123ENTERPRISE:user:U123");
     expect(prepared.ctxPayload.OriginatingTo).toBe("team:T123ENTERPRISE:user:U123");
     expect(prepared.ctxPayload.NativeChannelId).toBe("D999");
diff --git a/extensions/slack/src/monitor/message-handler/prepare.ts b/extensions/slack/src/monitor/message-handler/prepare.ts
index 7898edc16864..1dd1b9e443c6 100644
--- a/extensions/slack/src/monitor/message-handler/prepare.ts
+++ b/extensions/slack/src/monitor/message-handler/prepare.ts
@@ -77,6 +77,7 @@ import { escapeSlackMrkdwn } from "../mrkdwn.js";
 import { resolveSlackRoomContextHints } from "../room-context.js";
 import { sendMessageSlack } from "../send.runtime.js";
 import { resolveSlackThreadStarter, type SlackThreadStarter } from "../thread.js";
+import { qualifySlackRoutePeerId } from "../workspace-routing.js";
 import {
   discardSlackPreflightMedia,
   findCaptionlessSlackAudioFile,
@@ -1691,6 +1692,14 @@ export async function prepareSlackMessage(params: {
     conversation: {
       kind: chatType,
       id: message.channel,
+      routePeer: {
+        kind: chatType,
+        id: qualifySlackRoutePeerId({
+          id: isDirectMessage ? (message.user ?? "unknown") : message.channel,
+          kind: isDirectMessage ? "user" : "channel",
+          eventScope: opts.eventScope,
+        }),
+      },
       label: envelopeFrom,
       spaceId: opts.eventScope?.teamId || ctx.teamId || undefined,
       threadId: boundMessageThreadId,
diff --git a/extensions/slack/src/monitor/workspace-routing.ts b/extensions/slack/src/monitor/workspace-routing.ts
index 9a2b207082af..22d57577aceb 100644
--- a/extensions/slack/src/monitor/workspace-routing.ts
+++ b/extensions/slack/src/monitor/workspace-routing.ts
@@ -14,7 +14,7 @@ export function resolveSlackEnterpriseMainDmSessionKey(params: {
 export function qualifySlackRoutePeerId(params: {
   id: string;
   kind: "user" | "channel";
-  eventScope?: SlackEventScope;
+  eventScope?: Pick<SlackEventScope, "teamId">;
 }): string {
   if (!params.eventScope) {
     return params.id;
@@ -24,7 +24,7 @@ export function qualifySlackRoutePeerId(params: {
 
 export function qualifySlackConversationId(
   conversationId: string,
-  eventScope?: SlackEventScope,
+  eventScope?: Pick<SlackEventScope, "teamId">,
 ): string {
   return eventScope
     ? `team:${encodeURIComponent(eventScope.teamId)}:${conversationId}`
diff --git a/extensions/telegram/src/bot-message-context.dm-topic-threadid.test.ts b/extensions/telegram/src/bot-message-context.dm-topic-threadid.test.ts
index 09279bcb0433..988e9c9811e4 100644
--- a/extensions/telegram/src/bot-message-context.dm-topic-threadid.test.ts
+++ b/extensions/telegram/src/bot-message-context.dm-topic-threadid.test.ts
@@ -113,6 +113,8 @@ describe("buildTelegramMessageContext DM topic threadId in deliveryContext (#889
     expect(buildChannelInboundEventContextMock).toHaveBeenCalledOnce();
     const [turnOptions] = buildChannelInboundEventContextMock.mock.calls.at(0) ?? [];
     expect(turnOptions?.channel).toBe("telegram");
+    expect(turnOptions?.conversation.routePeer).toEqual({ kind: "direct", id: "42" });
+    expect(turnOptions?.conversation.parentId).toBeUndefined();
     expect(turnOptions?.from).toBe("telegram:1234");
     expect(turnOptions?.sender?.isBot).toBe(true);
     expect(turnOptions?.message.rawBody).toBe("hello");
diff --git a/extensions/telegram/src/bot-message-context.session.ts b/extensions/telegram/src/bot-message-context.session.ts
index af2a8602e010..86e5f02d7e41 100644
--- a/extensions/telegram/src/bot-message-context.session.ts
+++ b/extensions/telegram/src/bot-message-context.session.ts
@@ -39,6 +39,7 @@ import {
   buildSenderName,
   buildTelegramGroupFrom,
   buildTelegramInboundOriginTarget,
+  buildTelegramParentPeer,
   describeReplyTarget,
   getTelegramTextParts,
   normalizeForwardedContext,
@@ -49,6 +50,7 @@ import {
 } from "./bot/helpers.js";
 import { renderTelegramTextEntities } from "./bot/inbound-text-entities.js";
 import type { TelegramContext } from "./bot/types.js";
+import { resolveTelegramDirectPeerId } from "./dm-session-key.js";
 import {
   resolveTelegramDirectToolPolicy,
   resolveTelegramGroupPromptSettings,
@@ -62,6 +64,7 @@ import {
 } from "./group-history-window.js";
 import { TELEGRAM_REPLY_CHAIN_MAX_DEPTH, type TelegramReplyChainEntry } from "./message-cache.js";
 import { resolveTelegramPromptMediaPath } from "./prompt-media-path.js";
+import { buildTelegramConversationId } from "./topic-conversation.js";
 
 type TelegramMentionFacts = NonNullable<
   NonNullable<BuildChannelInboundEventContextParams["access"]>["mentions"]
@@ -673,7 +676,18 @@ export async function buildTelegramInboundContextPayload(params: {
     conversation: {
       kind: conversationKind,
       id: String(chatId),
+      routePeer: {
+        kind: conversationKind,
+        id: isGroup
+          ? buildTelegramConversationId({ chatId, thread: threadSpec })
+          : resolveTelegramDirectPeerId({ chatId, senderId }),
+      },
       label: conversationLabel,
+      parentId: buildTelegramParentPeer({
+        isGroup,
+        resolvedThreadId: threadSpec.id,
+        chatId,
+      })?.id,
       threadId: threadSpec.id != null ? String(threadSpec.id) : undefined,
     },
     route: {
diff --git a/extensions/telegram/src/bot-message-context.thread-binding.test.ts b/extensions/telegram/src/bot-message-context.thread-binding.test.ts
index de7c675d64e9..b74c6ed15328 100644
--- a/extensions/telegram/src/bot-message-context.thread-binding.test.ts
+++ b/extensions/telegram/src/bot-message-context.thread-binding.test.ts
@@ -117,7 +117,10 @@ describe("buildTelegramMessageContext thread binding override", () => {
         accountId: "default",
         sessionKey: "plugin-binding:openclaw-codex-app-server:session-1",
         agentId: "main",
-        bindingMode: { kind: "plugin-owned-runtime" },
+        bindingMode: {
+          kind: "plugin-owned-runtime",
+          pluginId: "openclaw-codex-app-server",
+        },
       }),
     );
 
diff --git a/extensions/telegram/src/bot-message-context.typing.test.ts b/extensions/telegram/src/bot-message-context.typing.test.ts
index b157e4edb8b1..691e79708310 100644
--- a/extensions/telegram/src/bot-message-context.typing.test.ts
+++ b/extensions/telegram/src/bot-message-context.typing.test.ts
@@ -197,6 +197,14 @@ describe("buildTelegramMessageContext typing", () => {
     expect(first).toHaveBeenCalledExactlyOnceWith(expectedBinding);
     expect(last).toHaveBeenCalledExactlyOnceWith(expectedBinding);
     expect(ctx?.ctxPayload.MessageSid).toBe("102");
+    expect(buildInboundContext).toHaveBeenCalledWith(
+      expect.objectContaining({
+        conversation: expect.objectContaining({
+          routePeer: { kind: "group", id: "-1001234567890:topic:99" },
+          parentId: "-1001234567890",
+        }),
+      }),
+    );
   });
 
   it("does not send forum topic typing for unaddressed require-mention messages", async () => {
diff --git a/extensions/telegram/src/bot-native-command-dispatch.routing.test.ts b/extensions/telegram/src/bot-native-command-dispatch.routing.test.ts
index 30146d6946bd..11c0391383c4 100644
--- a/extensions/telegram/src/bot-native-command-dispatch.routing.test.ts
+++ b/extensions/telegram/src/bot-native-command-dispatch.routing.test.ts
@@ -334,8 +334,10 @@ describe("Telegram native command dispatch routing", () => {
             {
               ctx?: {
                 CommandTargetSessionKey?: string;
+                ConversationRoutePeerId?: string;
                 MessageThreadId?: number;
                 OriginatingTo?: string;
+                ThreadParentId?: string;
               };
             },
           ]
@@ -345,8 +347,10 @@ describe("Telegram native command dispatch routing", () => {
         dispatchCall?.ctx,
         {
           CommandTargetSessionKey: "agent:main:telegram:group:-1001234567890:topic:42",
+          ConversationRoutePeerId: "-1001234567890:topic:42",
           MessageThreadId: 42,
           OriginatingTo: "telegram:-1001234567890:topic:42",
+          ThreadParentId: "-1001234567890",
         },
         "topic dispatch context",
       );
diff --git a/extensions/telegram/src/bot-native-command-dispatch.ts b/extensions/telegram/src/bot-native-command-dispatch.ts
index 2ac8fe605005..6f9cf4d39322 100644
--- a/extensions/telegram/src/bot-native-command-dispatch.ts
+++ b/extensions/telegram/src/bot-native-command-dispatch.ts
@@ -48,6 +48,7 @@ import {
 } from "./bot/helpers.js";
 import type { TelegramGetChat } from "./bot/types.js";
 import {
+  buildTelegramConversationRouteContext,
   resolveTelegramConversationRoute,
   resolveTelegramTargetSession,
 } from "./conversation-route.js";
@@ -545,6 +546,7 @@ export async function dispatchTelegramBuiltinTurn(params: {
       : `telegram:${dispatch.chatId}`,
     To: `slash:${dispatch.senderId || dispatch.chatId}`,
     ChatType: dispatch.isGroup ? "group" : "direct",
+    ...buildTelegramConversationRouteContext(dispatch),
     ConversationToolPolicy: dispatch.isGroup
       ? undefined
       : resolveTelegramDirectToolPolicy({
diff --git a/extensions/telegram/src/channel.ts b/extensions/telegram/src/channel.ts
index e132384bf4ad..76de7dfcf66f 100644
--- a/extensions/telegram/src/channel.ts
+++ b/extensions/telegram/src/channel.ts
@@ -62,6 +62,7 @@ import {
   resolveTelegramConfigAccessorAccount,
   telegramConfigAdapter,
 } from "./config-adapter.js";
+import { inspectTelegramConversationRouteOwner } from "./conversation-route-owner.js";
 import { resolveTelegramConversationBaseSessionKey } from "./conversation-route.js";
 import {
   listTelegramDirectoryGroupsFromConfig,
@@ -804,6 +805,7 @@ export const telegramPlugin = createChatChannelPlugin({
     },
     conversationBindings: {
       supportsCurrentConversationBinding: true,
+      bindingStore: "adapter",
       defaultTopLevelPlacement: "current",
       resolveConversationRef: ({
         accountId: _accountId,
@@ -897,6 +899,7 @@ export const telegramPlugin = createChatChannelPlugin({
     messaging: {
       defaultMarkdownTableMode: "block",
       targetPrefixes: ["telegram", "tg"],
+      resolveConversationRouteOwner: inspectTelegramConversationRouteOwner,
       numericTopicShorthand: true,
       normalizeTarget: normalizeTelegramMessagingTarget,
       resolveInboundConversation: ({ to, conversationId, threadId }) =>
diff --git a/extensions/telegram/src/conversation-route-owner.test.ts b/extensions/telegram/src/conversation-route-owner.test.ts
new file mode 100644
index 000000000000..d09bb6a89bf2
--- /dev/null
+++ b/extensions/telegram/src/conversation-route-owner.test.ts
@@ -0,0 +1,133 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import {
+  registerSessionBindingAdapter,
+  type SessionBindingAdapter,
+  testing,
+  unregisterSessionBindingAdapter,
+} from "openclaw/plugin-sdk/conversation-runtime";
+import {
+  createTestRegistry,
+  resetPluginRuntimeStateForTest,
+  setActivePluginRegistry,
+} from "openclaw/plugin-sdk/plugin-test-runtime";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { inspectTelegramConversationRouteOwner } from "./conversation-route-owner.js";
+
+describe("inspectTelegramConversationRouteOwner", () => {
+  let adapter: SessionBindingAdapter;
+
+  beforeEach(() => {
+    resetPluginRuntimeStateForTest();
+    setActivePluginRegistry(
+      createTestRegistry([
+        {
+          pluginId: "telegram",
+          source: "test",
+          plugin: {
+            id: "telegram",
+            meta: { aliases: [] },
+            conversationBindings: {
+              supportsCurrentConversationBinding: true,
+              createManager: () => ({ stop: () => undefined }),
+            },
+          },
+        },
+      ]),
+    );
+    testing.resetSessionBindingAdaptersForTests();
+    adapter = {
+      channel: "telegram",
+      accountId: "default",
+      listBySession: () => [],
+      resolveByConversation: () => null,
+    };
+    registerSessionBindingAdapter(adapter);
+  });
+
+  afterEach(() => {
+    resetPluginRuntimeStateForTest();
+    testing.resetSessionBindingAdaptersForTests();
+  });
+
+  it("replays topic config and runtime precedence without touching liveness", () => {
+    const cfg: OpenClawConfig = {
+      channels: {
+        telegram: {
+          groups: { "-100123": { topics: { "42": { agentId: "configured" } } } },
+        },
+      },
+    };
+    const touch = vi.fn();
+    registerSessionBindingAdapter({
+      channel: "telegram",
+      accountId: "default",
+      listBySession: () => [],
+      resolveByConversation: (conversation) => ({
+        bindingId: "binding-topic",
+        targetSessionKey: "agent:runtime:bound",
+        targetKind: "session",
+        conversation,
+        status: "active",
+        boundAt: 1,
+      }),
+      touch,
+    });
+
+    expect(
+      inspectTelegramConversationRouteOwner({
+        cfg,
+        accountId: "default",
+        conversation: { kind: "group", peerId: "-100123:topic:42", threadId: "42" },
+      }),
+    ).toEqual({ kind: "agent", agentId: "runtime" });
+    expect(touch).not.toHaveBeenCalled();
+  });
+
+  it("reports a temporary adapter gap only while thread bindings are enabled", () => {
+    unregisterSessionBindingAdapter({ channel: "telegram", accountId: "default", adapter });
+    const conversation = {
+      kind: "group" as const,
+      peerId: "-100123:topic:42",
+      threadId: "42",
+    };
+
+    expect(
+      inspectTelegramConversationRouteOwner({ cfg: {}, accountId: "default", conversation }),
+    ).toEqual({ kind: "unavailable" });
+    expect(
+      inspectTelegramConversationRouteOwner({
+        cfg: { channels: { telegram: { threadBindings: { enabled: false } } } },
+        accountId: "default",
+        conversation,
+      }),
+    ).toEqual({ kind: "agent", agentId: "main" });
+  });
+
+  it("keeps the direct sender route separate from its delivery chat", () => {
+    const resolveByConversation = vi.fn((conversation) => ({
+      bindingId: "binding-dm",
+      targetSessionKey: "agent:runtime:bound",
+      targetKind: "session" as const,
+      conversation,
+      status: "active" as const,
+      boundAt: 1,
+    }));
+    registerSessionBindingAdapter({
+      channel: "telegram",
+      accountId: "default",
+      listBySession: () => [],
+      resolveByConversation,
+    });
+
+    expect(
+      inspectTelegramConversationRouteOwner({
+        cfg: {},
+        accountId: "default",
+        conversation: { kind: "direct", peerId: "1001", target: "2002" },
+      }),
+    ).toEqual({ kind: "agent", agentId: "runtime" });
+    expect(resolveByConversation).toHaveBeenCalledWith(
+      expect.objectContaining({ conversationId: "2002" }),
+    );
+  });
+});
diff --git a/extensions/telegram/src/conversation-route-owner.ts b/extensions/telegram/src/conversation-route-owner.ts
new file mode 100644
index 000000000000..5478ba962dc5
--- /dev/null
+++ b/extensions/telegram/src/conversation-route-owner.ts
@@ -0,0 +1,90 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import { resolveThreadBindingSpawnPolicy } from "openclaw/plugin-sdk/conversation-runtime";
+import { parseStrictNonNegativeInteger } from "openclaw/plugin-sdk/number-runtime";
+import { resolveTelegramAccount } from "./accounts.js";
+import { inspectTelegramConversationRoute } from "./conversation-route.js";
+import { resolveTelegramScopedGroupConfig } from "./group-config-helpers.js";
+import { parseTelegramTarget } from "./targets.js";
+import type { TelegramThreadSpec } from "./thread-spec.js";
+
+function resolveInspectionThread(params: {
+  kind: "direct" | "group" | "channel";
+  peerId: string;
+  target?: string;
+  threadId?: string;
+}): { chatId: string; threadSpec: TelegramThreadSpec } | null {
+  const target = parseTelegramTarget(params.target?.trim() || params.peerId);
+  const chatId = target.chatId.trim();
+  if (!chatId) {
+    return null;
+  }
+  if (target.directMessagesTopicId != null) {
+    return {
+      chatId,
+      threadSpec: { id: target.directMessagesTopicId, scope: "direct-messages" },
+    };
+  }
+  if (target.messageThreadId != null) {
+    return { chatId, threadSpec: { id: target.messageThreadId, scope: "forum" } };
+  }
+  const threadId = parseStrictNonNegativeInteger(params.threadId);
+  return {
+    chatId,
+    threadSpec:
+      threadId == null
+        ? { scope: "none" }
+        : { id: threadId, scope: params.kind === "direct" ? "dm" : "forum" },
+  };
+}
+
+export function inspectTelegramConversationRouteOwner(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  conversation: {
+    kind: "direct" | "group" | "channel";
+    peerId: string;
+    target?: string;
+    threadId?: string;
+  };
+}) {
+  const parsed = resolveInspectionThread(params.conversation);
+  if (!parsed) {
+    return null;
+  }
+  const account = resolveTelegramAccount({ cfg: params.cfg, accountId: params.accountId });
+  const { topicConfig } = resolveTelegramScopedGroupConfig(
+    account.config,
+    parsed.chatId,
+    parsed.threadSpec.id,
+  );
+  const result = inspectTelegramConversationRoute({
+    cfg: params.cfg,
+    accountId: account.accountId,
+    chatId: parsed.chatId,
+    isGroup: params.conversation.kind !== "direct",
+    threadSpec: parsed.threadSpec,
+    senderId: params.conversation.kind === "direct" ? params.conversation.peerId : undefined,
+    topicAgentId: topicConfig?.agentId,
+  });
+  if (
+    !result.bindingOwnerAvailable &&
+    resolveThreadBindingSpawnPolicy({
+      cfg: params.cfg,
+      channel: "telegram",
+      accountId: params.accountId,
+      kind: "subagent",
+    }).enabled
+  ) {
+    return { kind: "unavailable" as const };
+  }
+  if (result.bindingMode.kind !== "plugin-owned-runtime") {
+    return { kind: "agent" as const, agentId: result.route.agentId };
+  }
+  return result.bindingMode.pluginId
+    ? {
+        kind: "plugin" as const,
+        pluginId: result.bindingMode.pluginId,
+        fallbackAgentId: result.route.agentId,
+      }
+    : null;
+}
diff --git a/extensions/telegram/src/conversation-route.base-session-key.test.ts b/extensions/telegram/src/conversation-route.base-session-key.test.ts
index ef1a629473ab..8c29371b53d2 100644
--- a/extensions/telegram/src/conversation-route.base-session-key.test.ts
+++ b/extensions/telegram/src/conversation-route.base-session-key.test.ts
@@ -204,7 +204,10 @@ describe("resolveTelegramConversationBaseSessionKey", () => {
     });
 
     expect(touch).toHaveBeenCalledWith("binding-plugin-owned", undefined);
-    expect(result.bindingMode).toEqual({ kind: "plugin-owned-runtime" });
+    expect(result.bindingMode).toEqual({
+      kind: "plugin-owned-runtime",
+      pluginId: "openclaw-codex-app-server",
+    });
     expect(result.route.agentId).toBe("main");
     expect(result.route.sessionKey).toBe("agent:main:telegram:group:-1001234567890:topic:11");
     expect(result.route.matchedBy).toBe("default");
diff --git a/extensions/telegram/src/conversation-route.ts b/extensions/telegram/src/conversation-route.ts
index 1bd2f523b017..e253e8eaf255 100644
--- a/extensions/telegram/src/conversation-route.ts
+++ b/extensions/telegram/src/conversation-route.ts
@@ -38,14 +38,15 @@ type TelegramConversationBindingMode =
       kind: "runtime-bound";
       sessionKey: string;
     }
-  | { kind: "plugin-owned-runtime" };
+  | { kind: "plugin-owned-runtime"; pluginId: string };
 
 type TelegramConversationRouteResult = {
   route: TelegramResolvedRoute;
   bindingMode: TelegramConversationBindingMode;
+  bindingOwnerAvailable: boolean;
 };
 
-export function resolveTelegramConversationRoute(params: {
+type ResolveTelegramConversationRouteParams = {
   cfg: OpenClawConfig;
   accountId: string;
   chatId: number | string;
@@ -53,7 +54,28 @@ export function resolveTelegramConversationRoute(params: {
   threadSpec: TelegramThreadSpec;
   senderId?: string | number | null;
   topicAgentId?: string | null;
-}): TelegramConversationRouteResult {
+};
+
+export function buildTelegramConversationRouteContext(params: {
+  chatId: number | string;
+  isGroup: boolean;
+  threadSpec: TelegramThreadSpec;
+  senderId?: string | number | null;
+  resolvedThreadId?: number;
+}) {
+  return {
+    ConversationRouteContextObserved: true,
+    ConversationRoutePeerId: params.isGroup
+      ? buildTelegramConversationId({ chatId: params.chatId, thread: params.threadSpec })
+      : resolveTelegramDirectPeerId(params),
+    ThreadParentId: buildTelegramParentPeer(params)?.id,
+  };
+}
+
+function resolveTelegramConversationRouteWithRuntimePolicy(
+  params: ResolveTelegramConversationRouteParams,
+  touchRuntimeBinding: boolean,
+): TelegramConversationRouteResult {
   const resolvedThreadId = params.threadSpec.id;
   const conversationId = buildTelegramConversationId({
     chatId: params.chatId,
@@ -141,6 +163,7 @@ export function resolveTelegramConversationRoute(params: {
   const runtimeBindingConversationId = conversationId;
   const runtimeRoute = resolveRuntimeConversationBindingRoute({
     route,
+    touchBinding: touchRuntimeBinding,
     conversation: {
       channel: "telegram",
       accountId: params.accountId,
@@ -151,7 +174,7 @@ export function resolveTelegramConversationRoute(params: {
   if (runtimeRoute.bindingRecord) {
     bindingMode = runtimeRoute.boundSessionKey
       ? { kind: "runtime-bound", sessionKey: runtimeRoute.boundSessionKey }
-      : { kind: "plugin-owned-runtime" };
+      : { kind: "plugin-owned-runtime", pluginId: runtimeRoute.pluginId ?? "" };
     logVerbose(
       runtimeRoute.boundSessionKey
         ? `telegram: routed via bound conversation ${runtimeBindingConversationId} -> ${runtimeRoute.boundSessionKey}`
@@ -162,9 +185,23 @@ export function resolveTelegramConversationRoute(params: {
   return {
     route,
     bindingMode,
+    bindingOwnerAvailable: runtimeRoute.bindingOwnerAvailable ?? true,
   };
 }
 
+export function resolveTelegramConversationRoute(
+  params: ResolveTelegramConversationRouteParams,
+): TelegramConversationRouteResult {
+  return resolveTelegramConversationRouteWithRuntimePolicy(params, true);
+}
+
+/** Revalidates route ownership without extending runtime-binding liveness. */
+export function inspectTelegramConversationRoute(
+  params: ResolveTelegramConversationRouteParams,
+): TelegramConversationRouteResult {
+  return resolveTelegramConversationRouteWithRuntimePolicy(params, false);
+}
+
 export function resolveTelegramConversationBaseSessionKey(
   params: Parameters<typeof resolveTelegramNamedAccountBaseSessionKey>[1],
 ): string {
diff --git a/package.json b/package.json
index 0187123a4831..b334f187d3bd 100644
--- a/package.json
+++ b/package.json
@@ -703,6 +703,10 @@
     "./plugin-sdk/media-generation-runtime": {
       "default": "./dist/plugin-sdk/media-generation-runtime.js"
     },
+    "./plugin-sdk/conversation-binding-inspection-runtime": {
+      "types": "./dist/plugin-sdk/conversation-binding-inspection-runtime.d.ts",
+      "default": "./dist/plugin-sdk/conversation-binding-inspection-runtime.js"
+    },
     "./plugin-sdk/conversation-binding-runtime": {
       "default": "./dist/plugin-sdk/conversation-binding-runtime.js"
     },
diff --git a/scripts/fixtures/packed-plugin-sdk-type-smoke.ts b/scripts/fixtures/packed-plugin-sdk-type-smoke.ts
index f7cb6a4f678e..42ab11010943 100644
--- a/scripts/fixtures/packed-plugin-sdk-type-smoke.ts
+++ b/scripts/fixtures/packed-plugin-sdk-type-smoke.ts
@@ -1,4 +1,9 @@
 // Packed Plugin Sdk Type Smoke script supports OpenClaw repository automation.
+import {
+  inspectConversationBinding,
+  type ConversationBindingInspection,
+} from "openclaw/plugin-sdk/conversation-binding-inspection-runtime";
+import type { ChannelMessagingAdapter } from "openclaw/plugin-sdk/core";
 type PublicPluginSdkModules = [
   typeof import("openclaw/plugin-sdk/core"),
   typeof import("openclaw/plugin-sdk/channel-entry-contract"),
@@ -8,5 +13,17 @@ type PublicPluginSdkModules = [
 ];
 
 const resolvedModules = null as unknown as PublicPluginSdkModules;
+const routeOwnerResolver: NonNullable<ChannelMessagingAdapter["resolveConversationRouteOwner"]> = ({
+  accountId,
+  conversation,
+}) => {
+  const inspection: ConversationBindingInspection = inspectConversationBinding({
+    channel: "fixture-channel",
+    accountId,
+    conversationId: conversation.target ?? conversation.peerId,
+  });
+  return inspection.status === "unavailable" ? { kind: "unavailable" } : undefined;
+};
 
 void resolvedModules;
+void routeOwnerResolver;
diff --git a/scripts/lib/plugin-sdk-doc-metadata.ts b/scripts/lib/plugin-sdk-doc-metadata.ts
index 5a3bbbaf8e2c..4313e218e596 100644
--- a/scripts/lib/plugin-sdk-doc-metadata.ts
+++ b/scripts/lib/plugin-sdk-doc-metadata.ts
@@ -90,6 +90,9 @@ export const pluginSdkDocMetadata = {
   "session-store-runtime": {
     category: "runtime",
   },
+  "conversation-binding-inspection-runtime": {
+    category: "runtime",
+  },
   "agent-scope-runtime": {
     category: "runtime",
   },
diff --git a/scripts/lib/plugin-sdk-entrypoints.json b/scripts/lib/plugin-sdk-entrypoints.json
index 5f9e98ad5d0c..717aa626aeff 100644
--- a/scripts/lib/plugin-sdk-entrypoints.json
+++ b/scripts/lib/plugin-sdk-entrypoints.json
@@ -86,6 +86,7 @@
   "media-mime",
   "embedding-providers",
   "media-generation-runtime",
+  "conversation-binding-inspection-runtime",
   "conversation-binding-runtime",
   "conversation-runtime",
   "thread-bindings-runtime",
diff --git a/scripts/plugin-sdk-surface-report.mts b/scripts/plugin-sdk-surface-report.mts
index 218fa3454d81..288c75e13adf 100644
--- a/scripts/plugin-sdk-surface-report.mts
+++ b/scripts/plugin-sdk-surface-report.mts
@@ -196,7 +196,8 @@ export function readPluginSdkSurfaceBudgets(env: NodeJS.ProcessEnv = process.env
       // +1: canonical Computer Use wire contract and node-host provider seam.
       // -1: retire the deprecated messaging-targets subpath.
       // +2: bounded provider streams and read-only SecretRef resolution.
-      146,
+      // +1: read-only authoritative conversation-binding inspection for route-owner plugins.
+      147,
       env,
     ),
     publicExports: readPluginSdkSurfaceBudgetEnv(
@@ -307,7 +308,8 @@ export function readPluginSdkSurfaceBudgets(env: NodeJS.ProcessEnv = process.env
       // +1: named bounded structured-input surface for native harness protocol adapters.
       // +1: OpenAI-compatible video execution in the existing media-understanding owner.
       // -2: retire the uncalled secret-plan target resolver and its result type.
-      4335,
+      // +2: conversation-binding inspection result and runtime inspector.
+      4337,
       env,
     ),
     publicFunctionExports: readPluginSdkSurfaceBudgetEnv(
@@ -396,7 +398,8 @@ export function readPluginSdkSurfaceBudgets(env: NodeJS.ProcessEnv = process.env
       // -1: remove the test-only channel activity reset export.
       // +1: OpenAI-compatible video execution in the existing media-understanding owner.
       // -1: retire the uncalled secret-plan target resolver.
-      2577,
+      // +1: read-only authoritative conversation-binding inspector.
+      2578,
       env,
     ),
     publicDeprecatedExports: readPluginSdkSurfaceBudgetEnv(
diff --git a/src/auto-reply/reply/commands-acp.test.ts b/src/auto-reply/reply/commands-acp.test.ts
index 2c34cffdadc8..4797dcda301b 100644
--- a/src/auto-reply/reply/commands-acp.test.ts
+++ b/src/auto-reply/reply/commands-acp.test.ts
@@ -77,6 +77,12 @@ function createAcpCommandSessionBindingService() {
   return {
     bind: (input: unknown) => hoisted.sessionBindingBindMock(input),
     getCapabilities: forward((params: unknown) => hoisted.sessionBindingCapabilitiesMock(params)),
+    inspectByConversation: (
+      ref: unknown,
+    ): { status: "available"; binding: SessionBindingRecord | null } => ({
+      status: "available",
+      binding: hoisted.sessionBindingResolveByConversationMock(ref),
+    }),
     listBySession: (targetSessionKey: string) =>
       hoisted.sessionBindingListBySessionMock(targetSessionKey),
     resolveByConversation: (ref: unknown) => hoisted.sessionBindingResolveByConversationMock(ref),
diff --git a/src/auto-reply/reply/session.ts b/src/auto-reply/reply/session.ts
index dc9ba4480760..4106a917d6e6 100644
--- a/src/auto-reply/reply/session.ts
+++ b/src/auto-reply/reply/session.ts
@@ -11,6 +11,7 @@ import { clearAllCliSessions, getCliSessionBinding } from "../../agents/cli-sess
 import { resetRegisteredAgentHarnessSessions } from "../../agents/harness/registry.js";
 import { cleanupBrowserSessionsForLifecycleEnd } from "../../browser-lifecycle-cleanup.js";
 import { normalizeChatType } from "../../channels/chat-type.js";
+import { conversationRouteContextFromMsgContext } from "../../config/sessions/conversation-route-context.js";
 import { resolveGroupSessionKey } from "../../config/sessions/group.js";
 import {
   hasTerminalMainSessionTranscriptNewerThanRegistry,
@@ -1032,6 +1033,11 @@ async function initSessionStateAttemptLocked(
       }
     },
     previousEntry: previousSessionEntry,
+    ...(!isSystemEvent &&
+    sessionCtxForState.InboundAccessAuthorized === true &&
+    sessionCtxForState.ConversationRouteContextObserved === true
+      ? { routeContext: conversationRouteContextFromMsgContext(sessionCtxForState) ?? null }
+      : {}),
     retiredEntry: retiredLegacyMainDelivery,
     sessionEntry,
     sessionKey,
diff --git a/src/auto-reply/templating.ts b/src/auto-reply/templating.ts
index b239a05e3d9f..cc651a8b9e5a 100644
--- a/src/auto-reply/templating.ts
+++ b/src/auto-reply/templating.ts
@@ -413,6 +413,10 @@ export type MsgContext = Partial<CanonicalInboundText> & {
    * Correlation interceptors must fail closed when this proof is absent.
    */
   InboundAccessAuthorized?: boolean;
+  /** Internal marker that channel ingress authoritatively observed route-context facts. */
+  ConversationRouteContextObserved?: boolean;
+  /** Canonical peer used by route selection; delivery targets may use a different namespace. */
+  ConversationRoutePeerId?: string;
   /**
    * Internal flag for channels that emit message_received through a channel-specific
    * privacy gate before entering the shared reply dispatcher.
diff --git a/src/channels/direct-dm.test.ts b/src/channels/direct-dm.test.ts
index c714d743d5e8..55a99d6d1dd2 100644
--- a/src/channels/direct-dm.test.ts
+++ b/src/channels/direct-dm.test.ts
@@ -205,5 +205,6 @@ describe("dispatchInboundDirectDm", () => {
       to: "reef:bot-1",
       originatingTo: "reef:peer-1",
     });
+    expect(contextParams?.conversation.routePeer).toEqual({ kind: "direct", id: "peer-1" });
   });
 });
diff --git a/src/channels/direct-dm.ts b/src/channels/direct-dm.ts
index df70923db4f1..7bcfe7c5c970 100644
--- a/src/channels/direct-dm.ts
+++ b/src/channels/direct-dm.ts
@@ -92,7 +92,12 @@ async function buildDirectDmContext(
     timestamp: params.timestamp,
     from: params.senderAddress,
     sender: { id: params.senderId, name: params.conversationLabel },
-    conversation: { kind: "direct", id: params.peer.id, label: params.conversationLabel },
+    conversation: {
+      kind: "direct",
+      id: params.peer.id,
+      routePeer: params.peer,
+      label: params.conversationLabel,
+    },
     route: {
       agentId: route.agentId,
       accountId: route.accountId,
@@ -231,6 +236,10 @@ export async function dispatchInboundDirectDmWithRuntime(
     Timestamp: params.timestamp,
     CommandAuthorized: params.commandAuthorized,
     ...(params.inboundAccessAuthorized === true ? { InboundAccessAuthorized: true } : {}),
+    ...(params.inboundAccessAuthorized === true
+      ? { ConversationRouteContextObserved: true as const }
+      : {}),
+    ConversationRoutePeerId: params.peer.id,
     OriginatingChannel: params.originatingChannel ?? params.channel,
     OriginatingTo: params.originatingTo ?? params.senderAddress,
     NativeDirectUserId: params.peer.id,
diff --git a/src/channels/feedback-reflection.test.ts b/src/channels/feedback-reflection.test.ts
index b7beea0f5466..7200ce58fad6 100644
--- a/src/channels/feedback-reflection.test.ts
+++ b/src/channels/feedback-reflection.test.ts
@@ -92,7 +92,10 @@ describe("channel feedback reflection", () => {
         cfg,
         channel: "msteams",
         route: { agentId: "main", sessionKey: params.sessionKey },
-        ctxPayload: expect.objectContaining({ ChatType: "group" }),
+        ctxPayload: expect.objectContaining({
+          ChatType: "group",
+          ConversationRouteContextObserved: false,
+        }),
       }),
     );
     await expect(runChannelFeedbackReflection(params)).resolves.toEqual({ status: "cooldown" });
diff --git a/src/channels/feedback-reflection.ts b/src/channels/feedback-reflection.ts
index 6f25acaa8e07..21a387cfc85b 100644
--- a/src/channels/feedback-reflection.ts
+++ b/src/channels/feedback-reflection.ts
@@ -151,6 +151,7 @@ export async function runChannelFeedbackReflection(params: {
     reply: { to: target, originatingTo: target },
     message: { body, bodyForAgent: prompt, rawBody: prompt, commandBody: prompt },
     access: { commands: { authorized: false } },
+    extra: { ConversationRouteContextObserved: false },
   });
   const responses: string[] = [];
   await dispatchRoutedChannelTurn({
diff --git a/src/channels/inbound-event/context.test.ts b/src/channels/inbound-event/context.test.ts
index 5e793767e094..b27d4311eccc 100644
--- a/src/channels/inbound-event/context.test.ts
+++ b/src/channels/inbound-event/context.test.ts
@@ -21,6 +21,7 @@ function createBaseContextParams(
     conversation: {
       kind: "group",
       id: "room-1",
+      routePeer: { kind: "group", id: "route-room-1" },
     },
     route: {
       agentId: "main",
@@ -108,6 +109,14 @@ describe("resolveInboundSupplementalSenderAllowed", () => {
 });
 
 describe("buildChannelInboundEventContext", () => {
+  it("does not claim authoritative route facts when the producer omits the route peer", () => {
+    const ctx = buildTestInboundEventContext({
+      conversation: { kind: "group", id: "room-1" },
+    });
+
+    expect(ctx.ConversationRouteContextObserved).toBeUndefined();
+  });
+
   it("maps normalized inbound facts into a finalized message context", async () => {
     const ctx = buildChannelInboundEventContext({
       channel: "test",
@@ -128,6 +137,7 @@ describe("buildChannelInboundEventContext", () => {
       conversation: {
         kind: "group",
         id: "room-1",
+        routePeer: { kind: "group", id: "route-room-1" },
         label: "Room One",
         spaceId: "workspace",
         threadId: "thread-1",
@@ -204,6 +214,8 @@ describe("buildChannelInboundEventContext", () => {
     });
 
     expect(ctx.InboundAccessAuthorized).toBe(true);
+    expect(ctx.ConversationRouteContextObserved).toBe(true);
+    expect(ctx.ConversationRoutePeerId).toBe("route-room-1");
 
     const expectedFields = {
       Body: "[User One] hello",
diff --git a/src/channels/inbound-event/context.ts b/src/channels/inbound-event/context.ts
index adae40418027..1d8f6c041ae6 100644
--- a/src/channels/inbound-event/context.ts
+++ b/src/channels/inbound-event/context.ts
@@ -554,6 +554,7 @@ function buildChannelInboundEventContextValue(
     ReplyToIdFull: params.reply.replyToIdFull,
     ChatType: params.conversation.kind,
     ChatId: params.conversation.id,
+    ConversationRoutePeerId: params.conversation.routePeer?.id,
     ConversationLabel: params.conversation.label,
     GroupSubject: params.conversation.kind !== "direct" ? params.conversation.label : undefined,
     GroupSpace: params.conversation.spaceId,
@@ -586,6 +587,7 @@ function buildChannelInboundEventContextValue(
     // This builder is the post-admission boundary for channel events. Preserve
     // that fact so interceptors cannot bypass sender, route, or pairing gates.
     InboundAccessAuthorized: true,
+    ConversationRouteContextObserved: params.conversation.routePeer ? true : undefined,
     ...params.extra,
   };
   const finalizeParams = {
diff --git a/src/channels/plugins/binding-routing.test.ts b/src/channels/plugins/binding-routing.test.ts
index 72482911e613..484fc67eb2b8 100644
--- a/src/channels/plugins/binding-routing.test.ts
+++ b/src/channels/plugins/binding-routing.test.ts
@@ -10,6 +10,7 @@ import type { ResolvedAgentRoute } from "../../routing/resolve-route.js";
 import {
   ensureConfiguredBindingRouteReady,
   resolveRuntimeConversationBindingRoute,
+  type RuntimeConversationBindingRouteResult,
 } from "./binding-routing.js";
 import { registerStatefulBindingTargetDriver } from "./stateful-target-drivers.js";
 
@@ -62,6 +63,15 @@ describe("runtime conversation binding route", () => {
     testing.resetSessionBindingAdaptersForTests();
   });
 
+  it("keeps the stable runtime-route result structurally assignable", () => {
+    const result: RuntimeConversationBindingRouteResult = {
+      bindingRecord: null,
+      route: createRoute(),
+    };
+
+    expect(result.bindingOwnerAvailable).toBeUndefined();
+  });
+
   it("rewrites the route to a runtime-bound ACP session and touches the binding", () => {
     const binding = createBinding();
     const { resolveByConversation, touch } = registerAdapter(binding);
@@ -120,6 +130,24 @@ describe("runtime conversation binding route", () => {
     expect(result.route).toBe(route);
   });
 
+  it("inspects a runtime-bound route without touching the binding", () => {
+    const { touch } = registerAdapter(createBinding());
+
+    const result = resolveRuntimeConversationBindingRoute({
+      route: createRoute(),
+      touchBinding: false,
+      conversation: {
+        channel: "demo",
+        accountId: "default",
+        conversationId: "room-1",
+      },
+    });
+
+    expect(touch).not.toHaveBeenCalled();
+    expect(result.bindingOwnerAvailable).toBe(true);
+    expect(result.boundSessionKey).toBe("agent:review:acp:session-1");
+  });
+
   it("ignores runtime bindings that target isolated cron run sessions", () => {
     const route = createRoute();
     const binding = createBinding({
diff --git a/src/channels/plugins/binding-routing.ts b/src/channels/plugins/binding-routing.ts
index a34d9469b8f0..399135f2b72a 100644
--- a/src/channels/plugins/binding-routing.ts
+++ b/src/channels/plugins/binding-routing.ts
@@ -7,6 +7,7 @@ import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { logVerbose } from "../../globals.js";
 import {
   getSessionBindingService,
+  inspectSessionBindingByConversation,
   type ConversationRef,
   type SessionBindingRecord,
 } from "../../infra/outbound/session-binding-service.js";
@@ -34,10 +35,13 @@ export type ConfiguredBindingRouteResult = {
  * Route resolution after applying a runtime conversation binding record.
  */
 export type RuntimeConversationBindingRouteResult = {
+  /** False only when the authoritative channel-owned binding store is temporarily unavailable. */
+  bindingOwnerAvailable?: boolean;
   bindingRecord: SessionBindingRecord | null;
   route: ResolvedAgentRoute;
   boundSessionKey?: string;
   boundAgentId?: string;
+  pluginId?: string;
 };
 
 type ConfiguredBindingRouteConversationInput =
@@ -65,16 +69,19 @@ function resolveConfiguredBindingConversationRef(
   };
 }
 
-function isPluginOwnedRuntimeBindingRecord(record: SessionBindingRecord | null): boolean {
+function resolvePluginOwnedRuntimeBindingPluginId(
+  record: SessionBindingRecord | null,
+): string | undefined {
   const metadata = record?.metadata;
   if (!metadata || typeof metadata !== "object") {
-    return false;
+    return undefined;
   }
-  return (
+  const pluginId = metadata.pluginId;
+  const isPluginOwned =
     metadata.pluginBindingOwner === "plugin" &&
-    typeof metadata.pluginId === "string" &&
-    typeof metadata.pluginRoot === "string"
-  );
+    typeof pluginId === "string" &&
+    typeof metadata.pluginRoot === "string";
+  return isPluginOwned ? pluginId.trim() || undefined : undefined;
 }
 
 /**
@@ -132,14 +139,25 @@ export function resolveConfiguredBindingRoute(
 export function resolveRuntimeConversationBindingRoute(
   params: {
     route: ResolvedAgentRoute;
+    /** Set false for read-only ownership checks that must not extend binding liveness. */
+    touchBinding?: boolean;
   } & ConfiguredBindingRouteConversationInput,
 ): RuntimeConversationBindingRouteResult {
-  const bindingRecord = getSessionBindingService().resolveByConversation(
+  const inspection = inspectSessionBindingByConversation(
     resolveConfiguredBindingConversationRef(params),
   );
+  if (inspection.status === "unavailable") {
+    return {
+      bindingOwnerAvailable: false,
+      bindingRecord: null,
+      route: params.route,
+    };
+  }
+  const bindingRecord = inspection.binding;
   const boundSessionKey = bindingRecord?.targetSessionKey?.trim();
   if (!bindingRecord || !boundSessionKey) {
     return {
+      bindingOwnerAvailable: true,
       bindingRecord: null,
       route: params.route,
     };
@@ -151,23 +169,30 @@ export function resolveRuntimeConversationBindingRoute(
       `ignored runtime conversation binding ${bindingRecord.bindingId} to isolated cron run session ${boundSessionKey}`,
     );
     return {
+      bindingOwnerAvailable: true,
       bindingRecord: null,
       route: params.route,
     };
   }
 
-  getSessionBindingService().touch(bindingRecord.bindingId);
-  if (isPluginOwnedRuntimeBindingRecord(bindingRecord)) {
+  if (params.touchBinding !== false) {
+    getSessionBindingService().touch(bindingRecord.bindingId);
+  }
+  const pluginId = resolvePluginOwnedRuntimeBindingPluginId(bindingRecord);
+  if (pluginId) {
     // Plugin-owned binding records are observed but not route-rewritten by core; the owning
     // plugin is responsible for its runtime target handoff.
     return {
+      bindingOwnerAvailable: true,
       bindingRecord,
+      pluginId,
       route: params.route,
     };
   }
 
   const boundAgentId = resolveAgentIdFromSessionKey(boundSessionKey) || params.route.agentId;
   return {
+    bindingOwnerAvailable: true,
     bindingRecord,
     boundSessionKey,
     boundAgentId,
diff --git a/src/channels/plugins/types.adapters.ts b/src/channels/plugins/types.adapters.ts
index 81fa497ad149..bfd397e8a524 100644
--- a/src/channels/plugins/types.adapters.ts
+++ b/src/channels/plugins/types.adapters.ts
@@ -739,6 +739,8 @@ export type ChannelConfiguredBindingProvider = {
 export type ChannelConversationBindingSupport = {
   supportsCurrentConversationBinding?: boolean;
   isCurrentConversationBindingSupported?: (params: { accountId: string }) => boolean;
+  /** Declares that live bindings come from a channel-registered adapter, never generic storage. */
+  bindingStore?: "adapter";
   /**
    * Preferred placement when a command is started from a top-level conversation
    * without an existing native thread id.
diff --git a/src/channels/plugins/types.core.ts b/src/channels/plugins/types.core.ts
index d0d7a52980cf..3812c293793e 100644
--- a/src/channels/plugins/types.core.ts
+++ b/src/channels/plugins/types.core.ts
@@ -494,6 +494,32 @@ export type ChannelMessagingAdapter = {
    * targets before plugin-specific normalization.
    */
   targetPrefixes?: readonly string[];
+  /** Re-resolve the current owner when channel behavior exceeds generic bindings. */
+  resolveConversationRouteOwner?: (params: {
+    cfg: OpenClawConfig;
+    accountId: string;
+    conversation: {
+      kind: "direct" | "group" | "channel";
+      peerId: string;
+      /** Canonical delivery target when it differs from the routing peer. */
+      target?: string;
+      threadId?: string;
+      nativeChannelId?: string;
+      context?: {
+        parentPeerId?: string;
+        guildId?: string;
+        teamId?: string;
+        memberRoleIds?: string[];
+      };
+    };
+  }) =>
+    // `undefined` delegates to core, `null` denies ownership, and `unavailable`
+    // preserves temporary owner-store outages as retryable delivery failures.
+    | { kind: "agent"; agentId: string }
+    | { kind: "plugin"; pluginId: string; fallbackAgentId: string }
+    | { kind: "unavailable" }
+    | null
+    | undefined;
   /** DM targets rebuilt from session keys require an explicit `user:` kind prefix. */
   directTargetStyle?: "user-prefixed";
   /** Equality rule for ids carried by prefixed outbound targets. */
diff --git a/src/config/sessions/conversation-identity.ts b/src/config/sessions/conversation-identity.ts
index d464df793b04..098862efa78c 100644
--- a/src/config/sessions/conversation-identity.ts
+++ b/src/config/sessions/conversation-identity.ts
@@ -14,6 +14,10 @@ import {
   sessionDeliveryOrigin,
 } from "../../utils/delivery-context.shared.js";
 import type { DeliveryContext } from "../../utils/delivery-context.types.js";
+import {
+  conversationRouteContextFromMsgContext,
+  type ConversationRouteContext,
+} from "./conversation-route-context.js";
 import { resolveGroupSessionKey } from "./group.js";
 import { deriveSessionOrigin } from "./metadata.js";
 import type { GroupKeyResolution, SessionEntry } from "./types.js";
@@ -155,6 +159,7 @@ export function buildConversationIdentity(params: {
 /** Derives a transport address from the canonical route snapshot persisted on a session. */
 export function conversationIdentityFromSessionEntry(
   entry: SessionEntry,
+  routeContext?: ConversationRouteContext | null,
 ): ConversationIdentity | null {
   const deliveryContext = deliveryContextFromSession(entry);
   const origin = sessionDeliveryOrigin(entry);
@@ -179,7 +184,7 @@ export function conversationIdentityFromSessionEntry(
     accountId: routeOwnsTarget ? deliveryContext?.accountId : origin?.accountId,
     kind,
     // Native ids remain descriptive metadata and cannot redirect a stored conversation ref.
-    peerId: pairedOriginPeerId ?? deliveryTarget,
+    peerId: routeContext?.peerId ?? pairedOriginPeerId ?? deliveryTarget,
     deliveryTarget,
     threadId: routeOwnsTarget ? deliveryContext?.threadId : origin?.threadId,
     nativeChannelId: origin?.nativeChannelId,
@@ -204,6 +209,7 @@ export function conversationIdentityFromMsgContext(params: {
   });
   const deliveryContext = mergeDeliveryContext(explicitDeliveryContext, routeDeliveryContext);
   const groupResolution = params.groupResolution ?? resolveGroupSessionKey(params.ctx);
+  const routeContext = conversationRouteContextFromMsgContext(params.ctx);
   const kind = groupResolution?.chatType ?? normalizeKind(params.ctx.ChatType);
   const directIngressTarget = kind === "direct" ? normalizeText(params.ctx.From) : undefined;
   // An explicit delivery context is already a paired route. Otherwise direct ingress
@@ -229,7 +235,7 @@ export function conversationIdentityFromMsgContext(params: {
       ? (route?.accountId ?? params.ctx.AccountId)
       : (deliveryContext?.accountId ?? route?.accountId ?? params.ctx.AccountId),
     kind,
-    peerId: deliveryTarget,
+    peerId: routeContext?.peerId ?? deliveryTarget,
     deliveryTarget,
     threadId: useDirectIngressTarget
       ? (route?.threadId ?? params.ctx.MessageThreadId)
diff --git a/src/config/sessions/conversation-registry.test.ts b/src/config/sessions/conversation-registry.test.ts
index eed55166c256..260171dc0cf4 100644
--- a/src/config/sessions/conversation-registry.test.ts
+++ b/src/config/sessions/conversation-registry.test.ts
@@ -15,7 +15,9 @@ import {
   resolveConversation,
 } from "./conversation-registry.js";
 import {
+  commitReplySessionInitialization,
   deleteSessionEntryLifecycle,
+  loadReplySessionInitializationSnapshot,
   upsertSessionEntryCore as upsertCanonicalSessionEntry,
 } from "./session-accessor.js";
 import {
@@ -110,6 +112,185 @@ describe("conversation registry", () => {
     );
   });
 
+  it("round-trips authoritative route context on its conversation association", async () => {
+    const sessionKey = "agent:main:discord:channel:ops";
+    const scope = { agentId: "main", sessionKey, storePath };
+    await upsertSessionEntry(scope, {
+      sessionId: "ops-session",
+      updatedAt: 100,
+      chatType: "channel",
+      deliveryContext: { channel: "discord", accountId: "default", to: "channel:ops" },
+    });
+    const snapshot = loadReplySessionInitializationSnapshot(scope);
+
+    const committed = await commitReplySessionInitialization({
+      activeSessionKey: sessionKey,
+      agentId: "main",
+      expectedRevision: snapshot.revision,
+      routeContext: {
+        peerId: "canonical-ops",
+        guildId: "guild-a",
+        parentPeerId: "parent-a",
+        memberRoleIds: ["support", "admin"],
+      },
+      sessionEntry: snapshot.currentEntry!,
+      sessionKey,
+      snapshotEntry: snapshot.currentEntry,
+      storePath,
+    });
+
+    expect(committed.ok).toBe(true);
+    const canonicalConversation = listConversations(scope).find(
+      (conversation) => conversation.peerId === "canonical-ops",
+    );
+    expect(canonicalConversation).toBeDefined();
+    const conversationRef = canonicalConversation!.conversationRef;
+    expect(resolveConversation({ agentId: "main", storePath }, conversationRef)).toMatchObject({
+      peerId: "canonical-ops",
+      observedFromSession: true,
+      routeContextObserved: true,
+      routeContext: {
+        peerId: "canonical-ops",
+        guildId: "guild-a",
+        parentPeerId: "parent-a",
+        memberRoleIds: ["admin", "support"],
+      },
+    });
+
+    await upsertCanonicalSessionEntry(scope, { label: "generic current write", updatedAt: 200 });
+    expect(
+      listConversations(scope).filter((conversation) => conversation.role === "primary"),
+    ).toEqual([expect.objectContaining({ conversationRef, peerId: "canonical-ops" })]);
+    const afterCurrentWrite = resolveConversation({ agentId: "main", storePath }, conversationRef);
+    expect(afterCurrentWrite).toMatchObject({
+      routeContextObserved: true,
+      routeContext: { guildId: "guild-a" },
+    });
+
+    const resolved = resolveSqliteReadScope(scope);
+    const database = openOpenClawAgentDatabase(toDatabaseOptions(resolved));
+    database.db
+      .prepare(
+        `INSERT INTO session_conversations (
+          session_id, conversation_id, role, first_seen_at, last_seen_at
+        ) VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(session_id, conversation_id, role) DO UPDATE SET
+          last_seen_at = excluded.last_seen_at`,
+      )
+      .run(
+        "ops-session",
+        conversationRef,
+        "primary",
+        afterCurrentWrite!.firstSeenAt,
+        afterCurrentWrite!.lastSeenAt,
+      );
+    closeOpenClawAgentDatabasesForTest();
+
+    expect(resolveConversation({ agentId: "main", storePath }, conversationRef)).not.toMatchObject({
+      routeContextObserved: true,
+    });
+    await upsertCanonicalSessionEntry(scope, {
+      label: "after older writer",
+      updatedAt: afterCurrentWrite!.lastSeenAt + 1,
+    });
+    expect(resolveConversation({ agentId: "main", storePath }, conversationRef)).not.toMatchObject({
+      routeContextObserved: true,
+    });
+  });
+
+  it("keeps route context with each conversation when a shared session changes primary", async () => {
+    const sessionKey = "agent:main:discord:channel:shared";
+    const scope = { agentId: "main", sessionKey, storePath };
+    const writeRoute = async (target: string, guildId: string, updatedAt: number) => {
+      await upsertSessionEntry(scope, {
+        sessionId: "shared-session",
+        updatedAt,
+        chatType: "channel",
+        deliveryContext: { channel: "discord", accountId: "default", to: target },
+      });
+      const snapshot = loadReplySessionInitializationSnapshot(scope);
+      const committed = await commitReplySessionInitialization({
+        activeSessionKey: sessionKey,
+        agentId: "main",
+        expectedRevision: snapshot.revision,
+        routeContext: { guildId },
+        sessionEntry: snapshot.currentEntry!,
+        sessionKey,
+        snapshotEntry: snapshot.currentEntry,
+        storePath,
+      });
+      expect(committed.ok).toBe(true);
+    };
+
+    await writeRoute("channel:alpha", "guild-alpha", 100);
+    await writeRoute("channel:beta", "guild-beta", 200);
+
+    expect(
+      listConversations(scope, { channel: "discord" })
+        .map(({ target, routeContext }) => ({ target, routeContext }))
+        .toSorted((left, right) => left.target.localeCompare(right.target)),
+    ).toEqual([
+      { target: "channel:alpha", routeContext: { guildId: "guild-alpha" } },
+      { target: "channel:beta", routeContext: { guildId: "guild-beta" } },
+    ]);
+  });
+
+  it("preserves context across an unobserved rollover and clears it on observed-empty ingress", async () => {
+    const sessionKey = "agent:main:discord:channel:rollover";
+    const scope = { agentId: "main", sessionKey, storePath };
+    await upsertSessionEntry(scope, {
+      sessionId: "before-rollover",
+      updatedAt: 100,
+      chatType: "channel",
+      deliveryContext: { channel: "discord", accountId: "default", to: "channel:rollover" },
+    });
+    let snapshot = loadReplySessionInitializationSnapshot(scope);
+    await commitReplySessionInitialization({
+      activeSessionKey: sessionKey,
+      agentId: "main",
+      expectedRevision: snapshot.revision,
+      routeContext: { guildId: "guild-a", memberRoleIds: ["support"] },
+      sessionEntry: snapshot.currentEntry!,
+      sessionKey,
+      snapshotEntry: snapshot.currentEntry,
+      storePath,
+    });
+
+    snapshot = loadReplySessionInitializationSnapshot(scope);
+    const rollover = await commitReplySessionInitialization({
+      activeSessionKey: sessionKey,
+      agentId: "main",
+      expectedRevision: snapshot.revision,
+      sessionEntry: { ...snapshot.currentEntry!, sessionId: "after-rollover", updatedAt: 200 },
+      sessionKey,
+      snapshotEntry: snapshot.currentEntry,
+      storePath,
+    });
+    expect(rollover.ok).toBe(true);
+    expect(listConversations(scope)[0]).toMatchObject({
+      sessionId: "after-rollover",
+      routeContextObserved: true,
+      routeContext: { guildId: "guild-a", memberRoleIds: ["support"] },
+    });
+
+    snapshot = loadReplySessionInitializationSnapshot(scope);
+    await commitReplySessionInitialization({
+      activeSessionKey: sessionKey,
+      agentId: "main",
+      expectedRevision: snapshot.revision,
+      routeContext: null,
+      sessionEntry: snapshot.currentEntry!,
+      sessionKey,
+      snapshotEntry: snapshot.currentEntry,
+      storePath,
+    });
+    expect(listConversations(scope)[0]).toMatchObject({
+      sessionId: "after-rollover",
+      routeContextObserved: true,
+    });
+    expect(listConversations(scope)[0]?.routeContext).toBeUndefined();
+  });
+
   it("orders fresh directory addresses with session-backed conversation activity", async () => {
     await upsertSessionEntry(
       { agentId: "main", sessionKey: "agent:main:reef:direct:peer-a", storePath },
diff --git a/src/config/sessions/conversation-registry.ts b/src/config/sessions/conversation-registry.ts
index 8212bb7201e6..ae9ad31a986c 100644
--- a/src/config/sessions/conversation-registry.ts
+++ b/src/config/sessions/conversation-registry.ts
@@ -3,6 +3,10 @@ import { executeSqliteQuerySync } from "../../infra/kysely-sync.js";
 import { openOpenClawAgentDatabase } from "../../state/openclaw-agent-db.js";
 import type { OpenClawConfig } from "../types.openclaw.js";
 import type { ConversationIdentity, ConversationKind } from "./conversation-identity.js";
+import {
+  parseStoredConversationRouteContext,
+  type ConversationRouteContext,
+} from "./conversation-route-context.js";
 import { resolveSessionStorePathCore } from "./paths.js";
 import { upsertConversationIdentity } from "./session-accessor.sqlite-conversation.js";
 import {
@@ -19,6 +23,7 @@ export type ConversationRecord = {
   channel: string;
   accountId: string;
   kind: ConversationKind;
+  peerId: string;
   target: string;
   parentConversationRef?: string;
   threadId?: string;
@@ -28,6 +33,12 @@ export type ConversationRecord = {
   sessionId?: string;
   sessionKey?: string;
   role?: "participant" | "primary" | "related";
+  /** True when this address has been linked to a session in this agent store. */
+  observedFromSession?: true;
+  /** Exact contextual facts from the authoritative inbound route. */
+  routeContext?: ConversationRouteContext;
+  /** True when authoritative ingress observed empty or populated route context. */
+  routeContextObserved?: true;
   firstSeenAt: number;
   lastSeenAt: number;
 };
@@ -59,8 +70,14 @@ function normalizeConversationRef(value: string): string {
   return normalized;
 }
 
+type MappedConversationRow = {
+  associationIsCurrent: boolean;
+  record: ConversationRecord;
+};
+
 function mapConversationRow(row: {
   account_id: string;
+  associated_session_id: string | null;
   channel: string;
   conversation_id: string;
   conversation_created_at: number;
@@ -75,11 +92,12 @@ function mapConversationRow(row: {
   parent_conversation_id: string | null;
   peer_id: string;
   role: string | null;
+  route_context_json: string | null;
   current_session_id: string | null;
   current_entry_json: string | null;
   current_session_key: string | null;
   thread_id: string | null;
-}): ConversationRecord | null {
+}): MappedConversationRow | null {
   if (row.kind !== "direct" && row.kind !== "group" && row.kind !== "channel") {
     return null;
   }
@@ -91,28 +109,41 @@ function mapConversationRow(row: {
     ? parseSessionEntryJson({ entry_json: row.current_entry_json })
     : null;
   const hasCurrentBinding = currentEntry?.sessionId === row.current_session_id;
+  const associationIsCurrent =
+    hasCurrentBinding && row.associated_session_id === row.current_session_id;
+  const routeContext = parseStoredConversationRouteContext(
+    row.route_context_json,
+    row.last_seen_at,
+  );
   return {
-    conversationRef: row.conversation_id,
-    channel: row.channel,
-    accountId: row.account_id,
-    kind: row.kind,
-    target: row.delivery_target,
-    ...(row.parent_conversation_id ? { parentConversationRef: row.parent_conversation_id } : {}),
-    ...(row.thread_id ? { threadId: row.thread_id } : {}),
-    ...(row.native_channel_id ? { nativeChannelId: row.native_channel_id } : {}),
-    ...(row.native_direct_user_id ? { nativeDirectUserId: row.native_direct_user_id } : {}),
-    ...(row.label ? { label: row.label } : {}),
-    // Only the current session_nodes row can bind an address. The joined
-    // window row may be historical after reset, rebind, or deletion.
-    ...(role && hasCurrentBinding && row.current_session_id && row.current_session_key
-      ? {
-          sessionId: row.current_session_id,
-          sessionKey: row.current_session_key,
-          role,
-        }
-      : {}),
-    firstSeenAt: row.first_seen_at ?? row.conversation_created_at,
-    lastSeenAt: row.last_seen_at ?? row.conversation_updated_at,
+    associationIsCurrent,
+    record: {
+      conversationRef: row.conversation_id,
+      channel: row.channel,
+      accountId: row.account_id,
+      kind: row.kind,
+      peerId: row.peer_id,
+      target: row.delivery_target,
+      ...(row.parent_conversation_id ? { parentConversationRef: row.parent_conversation_id } : {}),
+      ...(row.thread_id ? { threadId: row.thread_id } : {}),
+      ...(row.native_channel_id ? { nativeChannelId: row.native_channel_id } : {}),
+      ...(row.native_direct_user_id ? { nativeDirectUserId: row.native_direct_user_id } : {}),
+      ...(row.label ? { label: row.label } : {}),
+      // Only the current session_nodes row can bind an address. The joined
+      // window row may be historical after reset, rebind, or deletion.
+      ...(role && hasCurrentBinding && row.current_session_id && row.current_session_key
+        ? {
+            sessionId: row.current_session_id,
+            sessionKey: row.current_session_key,
+            role,
+          }
+        : {}),
+      ...(role ? { observedFromSession: true as const } : {}),
+      ...(routeContext ? { routeContextObserved: true as const } : {}),
+      ...(routeContext?.context ? { routeContext: routeContext.context } : {}),
+      firstSeenAt: row.first_seen_at ?? row.conversation_created_at,
+      lastSeenAt: row.last_seen_at ?? row.conversation_updated_at,
+    },
   };
 }
 
@@ -149,8 +180,10 @@ function selectConversationRows(
       "c.created_at as conversation_created_at",
       "c.updated_at as conversation_updated_at",
       "sc.role",
+      "sc.route_context_json",
       "sc.first_seen_at",
       "sc.last_seen_at",
+      "s.session_id as associated_session_id",
       "sn.current_session_id as current_session_id",
       "sn.entry_json as current_entry_json",
       "sn.session_key as current_session_key",
@@ -172,29 +205,45 @@ function selectConversationRows(
       .orderBy((eb) => eb.fn.coalesce("sc.last_seen_at", "c.updated_at"), "desc")
       .orderBy("sn.updated_at", "desc"),
   ).rows;
-  const unique = new Map<string, ConversationRecord>();
+  const unique = new Map<string, MappedConversationRow>();
   for (const row of rows) {
     const mapped = mapConversationRow(row);
     if (!mapped) {
       continue;
     }
-    const existing = unique.get(mapped.conversationRef);
+    const existing = unique.get(mapped.record.conversationRef);
     if (!existing) {
-      unique.set(mapped.conversationRef, mapped);
+      unique.set(mapped.record.conversationRef, mapped);
       continue;
     }
-    if (!existing.sessionId && mapped.sessionId && mapped.sessionKey && mapped.role) {
+    if (
+      !existing.associationIsCurrent &&
+      mapped.associationIsCurrent &&
+      mapped.record.sessionId &&
+      mapped.record.sessionKey &&
+      mapped.record.role
+    ) {
       // Keep the newest address activity while carrying forward the live binding
       // when a newer historical association has no current session entry.
-      unique.set(mapped.conversationRef, {
-        ...existing,
-        sessionId: mapped.sessionId,
-        sessionKey: mapped.sessionKey,
-        role: mapped.role,
+      const {
+        routeContext: _staleRouteContext,
+        routeContextObserved: _staleRouteContextObserved,
+        ...existingRecord
+      } = existing.record;
+      unique.set(mapped.record.conversationRef, {
+        associationIsCurrent: true,
+        record: {
+          ...existingRecord,
+          sessionId: mapped.record.sessionId,
+          sessionKey: mapped.record.sessionKey,
+          role: mapped.record.role,
+          ...(mapped.record.routeContextObserved ? { routeContextObserved: true as const } : {}),
+          ...(mapped.record.routeContext ? { routeContext: mapped.record.routeContext } : {}),
+        },
       });
     }
   }
-  const values = [...unique.values()];
+  const values = [...unique.values()].map(({ record }) => record);
   return options.limit === undefined ? values : values.slice(0, options.limit);
 }
 
diff --git a/src/config/sessions/conversation-route-context.test.ts b/src/config/sessions/conversation-route-context.test.ts
new file mode 100644
index 000000000000..97e2969a6e7a
--- /dev/null
+++ b/src/config/sessions/conversation-route-context.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import {
+  conversationRouteContextFromMsgContext,
+  parseConversationRouteContext,
+  parseStoredConversationRouteContext,
+  serializeStoredConversationRouteContext,
+} from "./conversation-route-context.js";
+
+describe("conversation route context", () => {
+  it("captures configured channel scopes deterministically", () => {
+    expect(
+      conversationRouteContextFromMsgContext({
+        OriginatingChannel: "Discord",
+        ConversationRoutePeerId: "channel-a",
+        GroupSpace: "guild-a",
+        ThreadParentId: "parent-a",
+        MemberRoleIds: ["support", "admin", "support"],
+      }),
+    ).toEqual({
+      peerId: "channel-a",
+      guildId: "guild-a",
+      parentPeerId: "parent-a",
+      memberRoleIds: ["admin", "support"],
+    });
+    expect(
+      conversationRouteContextFromMsgContext({
+        OriginatingChannel: "mattermost",
+        GroupSpace: "team-a",
+      }),
+    ).toEqual({ teamId: "team-a" });
+  });
+
+  it("rejects oversized route facts", () => {
+    expect(parseConversationRouteContext({ peerId: "x".repeat(513) })).toBeUndefined();
+    expect(parseConversationRouteContext({ guildId: "x".repeat(513) })).toBeUndefined();
+    expect(
+      parseConversationRouteContext({ guildId: "guild-a", parentPeerId: "x".repeat(513) }),
+    ).toBeUndefined();
+    expect(
+      parseConversationRouteContext({
+        memberRoleIds: Array.from({ length: 257 }, (_, i) => `${i}`),
+      }),
+    ).toBeUndefined();
+    expect(
+      parseConversationRouteContext({ peerId: "peer-a", memberRoleIds: ["role-a", ""] }),
+    ).toBeUndefined();
+  });
+
+  it("invalidates an envelope when an older writer advances association activity", () => {
+    const stored = serializeStoredConversationRouteContext({ guildId: "guild-a" }, 100);
+
+    expect(parseStoredConversationRouteContext(stored, 100)).toEqual({
+      context: { guildId: "guild-a" },
+    });
+    expect(parseStoredConversationRouteContext(stored, 200)).toBeUndefined();
+  });
+});
diff --git a/src/config/sessions/conversation-route-context.ts b/src/config/sessions/conversation-route-context.ts
new file mode 100644
index 000000000000..e3565afa9411
--- /dev/null
+++ b/src/config/sessions/conversation-route-context.ts
@@ -0,0 +1,165 @@
+import { randomUUID } from "node:crypto";
+import { isRecord } from "@openclaw/normalization-core/record-coerce";
+import {
+  normalizeOptionalLowercaseString,
+  normalizeOptionalString,
+} from "@openclaw/normalization-core/string-coerce";
+import type { MsgContext } from "../../auto-reply/templating.js";
+
+const MAX_ROUTE_CONTEXT_ID_LENGTH = 512;
+// Discord currently caps server roles below this; keep persisted authorization input bounded.
+const MAX_ROUTE_CONTEXT_ROLE_IDS = 256;
+const MAX_STORED_ROUTE_CONTEXT_LENGTH = 140_000;
+
+export type ConversationRouteContext = {
+  peerId?: string;
+  guildId?: string;
+  teamId?: string;
+  parentPeerId?: string;
+  memberRoleIds?: string[];
+};
+
+type ConversationRouteContextObservation = {
+  context?: ConversationRouteContext;
+};
+
+function normalizeBoundedId(value: unknown): string | undefined {
+  const normalized = normalizeOptionalString(value);
+  return normalized && normalized.length <= MAX_ROUTE_CONTEXT_ID_LENGTH ? normalized : undefined;
+}
+
+function normalizeRoleIds(value: unknown): { valid: boolean; value?: string[] } {
+  if (value === undefined) {
+    return { valid: true };
+  }
+  if (!Array.isArray(value) || value.length > MAX_ROUTE_CONTEXT_ROLE_IDS) {
+    return { valid: false };
+  }
+  const roleIds: string[] = [];
+  for (const item of value) {
+    const roleId = normalizeBoundedId(item);
+    if (!roleId) {
+      return { valid: false };
+    }
+    roleIds.push(roleId);
+  }
+  const unique = [...new Set(roleIds)].toSorted();
+  return unique.length > 0 ? { valid: true, value: unique } : { valid: true };
+}
+
+/** Parses the closed, bounded route facts used to replay configured routing precedence. */
+export function parseConversationRouteContext(
+  value: unknown,
+): ConversationRouteContext | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  const guildId = normalizeBoundedId(value.guildId);
+  const peerId = normalizeBoundedId(value.peerId);
+  const teamId = normalizeBoundedId(value.teamId);
+  const parentPeerId = normalizeBoundedId(value.parentPeerId);
+  const memberRoleIds = normalizeRoleIds(value.memberRoleIds);
+  if (
+    (value.peerId !== undefined && !peerId) ||
+    (value.guildId !== undefined && !guildId) ||
+    (value.teamId !== undefined && !teamId) ||
+    (value.parentPeerId !== undefined && !parentPeerId) ||
+    !memberRoleIds.valid
+  ) {
+    return undefined;
+  }
+  if (!peerId && !guildId && !teamId && !parentPeerId && !memberRoleIds.value) {
+    return undefined;
+  }
+  return {
+    ...(peerId ? { peerId } : {}),
+    ...(guildId ? { guildId } : {}),
+    ...(teamId ? { teamId } : {}),
+    ...(parentPeerId ? { parentPeerId } : {}),
+    ...(memberRoleIds.value ? { memberRoleIds: memberRoleIds.value } : {}),
+  };
+}
+
+/** Captures only authoritative inbound facts needed to replay configured route precedence. */
+export function conversationRouteContextFromMsgContext(
+  ctx: MsgContext,
+): ConversationRouteContext | undefined {
+  const channel = normalizeOptionalLowercaseString(ctx.OriginatingChannel ?? ctx.Provider);
+  const spaceId = normalizeBoundedId(ctx.GroupSpace);
+  const parentPeerId = normalizeBoundedId(ctx.ThreadParentId);
+  return parseConversationRouteContext({
+    ...(ctx.ConversationRoutePeerId !== undefined ? { peerId: ctx.ConversationRoutePeerId } : {}),
+    ...(channel === "discord" && spaceId ? { guildId: spaceId } : {}),
+    ...((channel === "slack" || channel === "mattermost" || channel === "msteams") && spaceId
+      ? { teamId: spaceId }
+      : {}),
+    ...(parentPeerId ? { parentPeerId } : {}),
+    ...(ctx.MemberRoleIds !== undefined ? { memberRoleIds: ctx.MemberRoleIds } : {}),
+  });
+}
+
+type StoredConversationRouteContext = {
+  version: 1;
+  // Current writers rotate this on every association update. Older writers preserve it,
+  // allowing the SQLite trigger to invalidate route facts even when activity time is unchanged.
+  writeId: string;
+  observedAt: number;
+  context: ConversationRouteContext | null;
+};
+
+export function serializeStoredConversationRouteContext(
+  context: ConversationRouteContext | null,
+  observedAt: number,
+): string {
+  const canonical = context === null ? null : parseConversationRouteContext(context);
+  if (context !== null && !canonical) {
+    throw new Error("Invalid conversation route context");
+  }
+  return JSON.stringify({
+    version: 1,
+    writeId: randomUUID(),
+    observedAt,
+    context: canonical ?? null,
+  } satisfies StoredConversationRouteContext);
+}
+
+export function parseStoredConversationRouteContext(
+  value: string | null,
+  expectedObservedAt: number | null,
+): ConversationRouteContextObservation | undefined {
+  if (!value || value.length > MAX_STORED_ROUTE_CONTEXT_LENGTH) {
+    return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value) as unknown;
+  } catch {
+    return undefined;
+  }
+  if (
+    !isRecord(parsed) ||
+    parsed.version !== 1 ||
+    typeof parsed.writeId !== "string" ||
+    parsed.writeId.length === 0 ||
+    typeof parsed.observedAt !== "number" ||
+    parsed.observedAt !== expectedObservedAt
+  ) {
+    return undefined;
+  }
+  const context = parseConversationRouteContext(parsed.context);
+  if (parsed.context !== null && !context) {
+    return undefined;
+  }
+  return context ? { context } : {};
+}
+
+export function refreshStoredConversationRouteContext(
+  value: string | null,
+  previousObservedAt: number,
+  observedAt: number,
+): string | null {
+  const stored = parseStoredConversationRouteContext(value, previousObservedAt);
+  return stored
+    ? serializeStoredConversationRouteContext(stored.context ?? null, observedAt)
+    : null;
+}
diff --git a/src/config/sessions/conversation-route-fingerprint.test.ts b/src/config/sessions/conversation-route-fingerprint.test.ts
new file mode 100644
index 000000000000..a74109783458
--- /dev/null
+++ b/src/config/sessions/conversation-route-fingerprint.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { resolveConversationRouteFingerprint } from "./conversation-route-fingerprint.js";
+
+const route = {
+  accountId: "default",
+  channel: "reef",
+  kind: "direct" as const,
+  peerId: "molty",
+  target: "user:molty",
+};
+
+describe("resolveConversationRouteFingerprint", () => {
+  it("binds both canonical ownership identity and physical delivery address", () => {
+    const expected = resolveConversationRouteFingerprint(route);
+
+    expect(resolveConversationRouteFingerprint({ ...route, target: "user:other" })).not.toBe(
+      expected,
+    );
+    expect(resolveConversationRouteFingerprint({ ...route, nativeDirectUserId: "other" })).not.toBe(
+      expected,
+    );
+  });
+
+  it("canonicalizes contextual role order before hashing", () => {
+    const first = resolveConversationRouteFingerprint({
+      ...route,
+      routeContextObserved: true,
+      routeContext: { guildId: "guild-1", memberRoleIds: ["role-b", "role-a"] },
+    });
+    const second = resolveConversationRouteFingerprint({
+      ...route,
+      routeContextObserved: true,
+      routeContext: { memberRoleIds: ["role-a", "role-b", "role-a"], guildId: "guild-1" },
+    });
+
+    expect(first).toBe(second);
+  });
+});
diff --git a/src/config/sessions/conversation-route-fingerprint.ts b/src/config/sessions/conversation-route-fingerprint.ts
new file mode 100644
index 000000000000..75d5e62b1588
--- /dev/null
+++ b/src/config/sessions/conversation-route-fingerprint.ts
@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+import type { ConversationRecord } from "./conversation-registry.js";
+import {
+  parseConversationRouteContext,
+  type ConversationRouteContext,
+} from "./conversation-route-context.js";
+
+type ConversationRouteFingerprintInput = Pick<
+  ConversationRecord,
+  | "accountId"
+  | "channel"
+  | "kind"
+  | "nativeDirectUserId"
+  | "parentConversationRef"
+  | "peerId"
+  | "target"
+  | "threadId"
+> & {
+  nativeChannelId?: string;
+  routeContext?: ConversationRouteContext;
+  routeContextObserved?: true;
+};
+
+/** Binds queued authority to the exact route facts admitted by the Gateway. */
+export function resolveConversationRouteFingerprint(
+  route: ConversationRouteFingerprintInput,
+): string {
+  const context = route.routeContext
+    ? parseConversationRouteContext(route.routeContext)
+    : undefined;
+  return createHash("sha256")
+    .update(
+      JSON.stringify([
+        route.channel,
+        route.accountId,
+        route.kind,
+        route.peerId,
+        route.target,
+        route.parentConversationRef ?? null,
+        route.threadId ?? null,
+        route.nativeChannelId ?? null,
+        route.nativeDirectUserId ?? null,
+        route.routeContextObserved === true,
+        context ?? null,
+      ]),
+    )
+    .digest("hex");
+}
diff --git a/src/config/sessions/session-accessor.lifecycle-types.ts b/src/config/sessions/session-accessor.lifecycle-types.ts
index 9b4fac3f00a1..b18cd3eed85c 100644
--- a/src/config/sessions/session-accessor.lifecycle-types.ts
+++ b/src/config/sessions/session-accessor.lifecycle-types.ts
@@ -1,4 +1,5 @@
 import type { OpenClawConfig } from "../types.openclaw.js";
+import type { ConversationRouteContext } from "./conversation-route-context.js";
 import type { SessionStateDeleteSnapshot } from "./session-accessor.sqlite-delete-snapshot.types.js";
 import type { SessionResetBoundaryReason } from "./session-reset-boundary-event.js";
 import type { InternalSessionEntry as SessionEntry } from "./types.js";
@@ -140,6 +141,8 @@ export class SessionEntryLifecycleUpsertConflictError extends Error {
 export type SessionEntryLifecycleUpsert = {
   sessionKey: string;
   resetBoundaryReason?: SessionResetBoundaryReason;
+  /** Authoritative route observation for this write; omitted writes preserve valid evidence. */
+  routeContext?: ConversationRouteContext | null;
 } & (
   | {
       entry: SessionEntry;
diff --git a/src/config/sessions/session-accessor.reset.ts b/src/config/sessions/session-accessor.reset.ts
index 3aad11263c71..65dc12745014 100644
--- a/src/config/sessions/session-accessor.reset.ts
+++ b/src/config/sessions/session-accessor.reset.ts
@@ -4,6 +4,7 @@ import {
   parseAgentSessionKey,
 } from "../../routing/session-key.js";
 import { createLazyRuntimeModule } from "../../shared/lazy-runtime.js";
+import type { ConversationRouteContext } from "./conversation-route-context.js";
 import {
   cloneSessionEntries,
   mergeConcurrentReplySessionMetadata,
@@ -156,6 +157,8 @@ export async function commitReplySessionInitialization(params: {
     context: ReplySessionInitializationCommitContext,
   ) => Promise<SessionEntry> | SessionEntry;
   resetBoundaryReason?: import("./session-reset-boundary-event.js").SessionResetBoundaryReason;
+  /** Authoritative contextual route facts observed by the admitted inbound turn. */
+  routeContext?: ConversationRouteContext | null;
   previousEntry?: SessionEntry;
   retiredEntry?: SessionEntryRetirement;
   sessionEntry: SessionEntry;
@@ -207,6 +210,7 @@ export async function commitReplySessionInitialization(params: {
   const upserts: SessionEntryLifecycleUpsert[] = [
     {
       sessionKey: resolved.normalizedKey,
+      ...(params.routeContext !== undefined ? { routeContext: params.routeContext } : {}),
       ...(params.resetBoundaryReason ? { resetBoundaryReason: params.resetBoundaryReason } : {}),
       buildEntry: async ({ store: currentStore }) => {
         const commitResolved = resolveSessionEntryFromStore({
diff --git a/src/config/sessions/session-accessor.sqlite-conversation.ts b/src/config/sessions/session-accessor.sqlite-conversation.ts
index c82bf725c6ae..7f7421f53991 100644
--- a/src/config/sessions/session-accessor.sqlite-conversation.ts
+++ b/src/config/sessions/session-accessor.sqlite-conversation.ts
@@ -1,9 +1,16 @@
+import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import { executeSqliteQuerySync } from "../../infra/kysely-sync.js";
 import type { OpenClawAgentDatabase } from "../../state/openclaw-agent-db.js";
 import {
   conversationIdentityFromSessionEntry,
   type ConversationIdentity,
 } from "./conversation-identity.js";
+import {
+  parseConversationRouteContext,
+  refreshStoredConversationRouteContext,
+  serializeStoredConversationRouteContext,
+  type ConversationRouteContext,
+} from "./conversation-route-context.js";
 import { getSessionKysely } from "./session-accessor.sqlite-scope.js";
 import type { SessionEntry } from "./types.js";
 
@@ -12,14 +19,25 @@ type SessionConversationRole = "participant" | "primary" | "related";
 type PreparedSessionConversation = {
   identity: ConversationIdentity;
   role: SessionConversationRole;
+  routeContext?: ConversationRouteContext | null;
 };
 
 /** Shared-main DMs multiplex peers through one context; every other routed session has one primary. */
-export function prepareSessionConversation(params: {
+function prepareSessionConversation(params: {
   entry: SessionEntry;
+  routeContext?: ConversationRouteContext | null;
   sessionScope: string;
 }): PreparedSessionConversation | null {
-  const identity = conversationIdentityFromSessionEntry(params.entry);
+  const routeContext =
+    params.routeContext === null
+      ? null
+      : params.routeContext === undefined
+        ? undefined
+        : parseConversationRouteContext(params.routeContext);
+  if (params.routeContext !== undefined && params.routeContext !== null && !routeContext) {
+    throw new Error("Invalid conversation route context");
+  }
+  const identity = conversationIdentityFromSessionEntry(params.entry, routeContext);
   if (!identity) {
     return null;
   }
@@ -29,9 +47,101 @@ export function prepareSessionConversation(params: {
       params.sessionScope === "shared-main" && identity.kind === "direct"
         ? "participant"
         : "primary",
+    ...(routeContext !== undefined ? { routeContext } : {}),
   };
 }
 
+/** Keeps a previously observed route peer when a generic session writer has no route facts. */
+function preserveSessionConversationIdentity(params: {
+  database: OpenClawAgentDatabase;
+  identity: ConversationIdentity;
+  sessionIds: string[];
+}): ConversationIdentity {
+  if (params.sessionIds.length === 0) {
+    return params.identity;
+  }
+  const db = getSessionKysely(params.database.db);
+  const row = executeSqliteQuerySync(
+    params.database.db,
+    db
+      .selectFrom("session_conversations as sc")
+      .innerJoin("conversations as c", "c.conversation_id", "sc.conversation_id")
+      .select([
+        "c.conversation_id",
+        "c.channel",
+        "c.account_id",
+        "c.kind",
+        "c.peer_id",
+        "c.delivery_target",
+        "c.parent_conversation_id",
+        "c.thread_id",
+        "c.native_channel_id",
+        "c.native_direct_user_id",
+        "c.label",
+        "c.metadata_json",
+      ])
+      .where("sc.session_id", "in", params.sessionIds)
+      .where("c.channel", "=", params.identity.channel)
+      .where("c.account_id", "=", params.identity.accountId)
+      .where("c.kind", "=", params.identity.kind)
+      .where("c.delivery_target", "=", params.identity.deliveryTarget)
+      .where("sc.role", "in", ["primary", "participant"])
+      .where("c.thread_id", params.identity.threadId ? "=" : "is", params.identity.threadId ?? null)
+      .orderBy("sc.last_seen_at", "desc")
+      .limit(1),
+  ).rows[0];
+  let metadata: Record<string, unknown> | undefined;
+  if (row?.metadata_json) {
+    try {
+      const parsed = JSON.parse(row.metadata_json) as unknown;
+      metadata = isRecord(parsed) ? parsed : undefined;
+    } catch {
+      metadata = undefined;
+    }
+  }
+  return row
+    ? {
+        conversationRef: row.conversation_id,
+        channel: row.channel,
+        accountId: row.account_id,
+        kind: params.identity.kind,
+        peerId: row.peer_id,
+        deliveryTarget: row.delivery_target,
+        ...(row.parent_conversation_id
+          ? { parentConversationRef: row.parent_conversation_id }
+          : {}),
+        ...(row.thread_id ? { threadId: row.thread_id } : {}),
+        ...(row.native_channel_id ? { nativeChannelId: row.native_channel_id } : {}),
+        ...(row.native_direct_user_id ? { nativeDirectUserId: row.native_direct_user_id } : {}),
+        ...((params.identity.label ?? row.label)
+          ? { label: params.identity.label ?? row.label! }
+          : {}),
+        ...(metadata ? { metadata } : {}),
+      }
+    : params.identity;
+}
+
+export function prepareSessionConversationForWrite(params: {
+  database: OpenClawAgentDatabase;
+  entry: SessionEntry;
+  previousEntry?: SessionEntry | null;
+  routeContext?: ConversationRouteContext | null;
+  sessionScope: string;
+}): PreparedSessionConversation | null {
+  const conversation = prepareSessionConversation(params);
+  if (!conversation || params.routeContext !== undefined) {
+    return conversation;
+  }
+  conversation.identity = preserveSessionConversationIdentity({
+    database: params.database,
+    identity: conversation.identity,
+    sessionIds: [params.entry.sessionId, params.previousEntry?.sessionId].filter(
+      (sessionId): sessionId is string => Boolean(sessionId),
+    ),
+  });
+  return conversation;
+}
+
 /** Upserts the address before the session row so its primary-conversation FK is always valid. */
 export function upsertConversationIdentity(
   database: OpenClawAgentDatabase,
@@ -81,18 +191,45 @@ export function upsertConversationIdentity(
 /** Links one external address to its local context without conflating the two identities. */
 export function linkSessionConversation(params: {
   database: OpenClawAgentDatabase;
+  previousSessionId?: string;
   sessionId: string;
   conversation: PreparedSessionConversation;
   updatedAt: number;
 }): void {
   const { database, sessionId, conversation, updatedAt } = params;
   const db = getSessionKysely(database.db);
+  const readAssociation = (candidateSessionId: string) =>
+    executeSqliteQuerySync(
+      database.db,
+      db
+        .selectFrom("session_conversations")
+        .select(["last_seen_at", "route_context_json"])
+        .where("session_id", "=", candidateSessionId)
+        .where("conversation_id", "=", conversation.identity.conversationRef)
+        .orderBy("last_seen_at", "desc")
+        .limit(1),
+    ).rows[0];
+  const existingAssociation =
+    readAssociation(sessionId) ??
+    (params.previousSessionId && params.previousSessionId !== sessionId
+      ? readAssociation(params.previousSessionId)
+      : undefined);
+  const routeContextJson =
+    conversation.routeContext === undefined
+      ? existingAssociation
+        ? refreshStoredConversationRouteContext(
+            existingAssociation.route_context_json,
+            existingAssociation.last_seen_at,
+            updatedAt,
+          )
+        : null
+      : serializeStoredConversationRouteContext(conversation.routeContext, updatedAt);
   if (conversation.role === "primary") {
     const stalePrimaryRows = executeSqliteQuerySync(
       database.db,
       db
         .selectFrom("session_conversations")
-        .select(["conversation_id", "first_seen_at"])
+        .select(["conversation_id", "first_seen_at", "last_seen_at", "route_context_json"])
         .where("session_id", "=", sessionId)
         .where("role", "=", "primary")
         .where("conversation_id", "!=", conversation.identity.conversationRef),
@@ -107,14 +244,20 @@ export function linkSessionConversation(params: {
               session_id: sessionId,
               conversation_id: row.conversation_id,
               role: "related",
+              route_context_json: refreshStoredConversationRouteContext(
+                row.route_context_json,
+                row.last_seen_at,
+                updatedAt,
+              ),
               first_seen_at: row.first_seen_at,
               last_seen_at: updatedAt,
             })),
           )
           .onConflict((conflict) =>
-            conflict.columns(["session_id", "conversation_id", "role"]).doUpdateSet({
+            conflict.columns(["session_id", "conversation_id", "role"]).doUpdateSet((eb) => ({
+              route_context_json: eb.ref("excluded.route_context_json"),
               last_seen_at: updatedAt,
-            }),
+            })),
           ),
       );
       executeSqliteQuerySync(
@@ -146,11 +289,13 @@ export function linkSessionConversation(params: {
         session_id: sessionId,
         conversation_id: conversation.identity.conversationRef,
         role: conversation.role,
+        route_context_json: routeContextJson,
         first_seen_at: updatedAt,
         last_seen_at: updatedAt,
       })
       .onConflict((conflict) =>
         conflict.columns(["session_id", "conversation_id", "role"]).doUpdateSet({
+          route_context_json: routeContextJson,
           last_seen_at: updatedAt,
         }),
       ),
diff --git a/src/config/sessions/session-accessor.sqlite-entry-store.ts b/src/config/sessions/session-accessor.sqlite-entry-store.ts
index 1955dd3ecc0a..ebedde3b3620 100644
--- a/src/config/sessions/session-accessor.sqlite-entry-store.ts
+++ b/src/config/sessions/session-accessor.sqlite-entry-store.ts
@@ -6,9 +6,10 @@ import {
 } from "../../infra/kysely-sync.js";
 import type { DB as OpenClawAgentKyselyDatabase } from "../../state/openclaw-agent-db.generated.js";
 import type { OpenClawAgentDatabase } from "../../state/openclaw-agent-db.js";
+import type { ConversationRouteContext } from "./conversation-route-context.js";
 import {
   linkSessionConversation,
-  prepareSessionConversation,
+  prepareSessionConversationForWrite,
   upsertConversationIdentity,
 } from "./session-accessor.sqlite-conversation.js";
 import {
@@ -577,6 +578,7 @@ export function writeSessionEntry(
     allowStoredAliases?: boolean;
     preserveNodeSuggestions?: boolean;
     previousEntry?: SessionEntry | null;
+    routeContext?: ConversationRouteContext | null;
   } = {},
 ): void {
   const db = getSessionKysely(database.db);
@@ -628,8 +630,11 @@ export function writeSessionEntry(
     readTranscriptMutationStateInTransaction(database, normalizedEntry.sessionId).updatedAt ??
     updatedAt;
   const boundSessionRoot = bindSessionRoot({ entry: normalizedEntry, sessionKey, updatedAt });
-  const conversation = prepareSessionConversation({
+  const conversation = prepareSessionConversationForWrite({
+    database,
     entry: normalizedEntry,
+    previousEntry,
+    ...(options.routeContext !== undefined ? { routeContext: options.routeContext } : {}),
     sessionScope: boundSessionRoot.session_scope,
   });
   if (conversation) {
@@ -724,6 +729,7 @@ export function writeSessionEntry(
   if (conversation) {
     linkSessionConversation({
       database,
+      ...(previousEntry?.sessionId ? { previousSessionId: previousEntry.sessionId } : {}),
       sessionId: sessionRow.session_id,
       conversation,
       updatedAt,
diff --git a/src/config/sessions/session-accessor.sqlite-entry.ts b/src/config/sessions/session-accessor.sqlite-entry.ts
index 957d44cf67bb..061b80fa1fc6 100644
--- a/src/config/sessions/session-accessor.sqlite-entry.ts
+++ b/src/config/sessions/session-accessor.sqlite-entry.ts
@@ -704,6 +704,7 @@ export async function updateSessionLastRoute(params: {
   ctx?: MsgContext;
   groupResolution?: GroupKeyResolution | null;
   createIfMissing?: boolean;
+  assertCommitAllowed?: () => void;
 }): Promise<SessionEntry | null> {
   const createIfMissing = params.createIfMissing ?? true;
   return await patchSessionEntryCore(
@@ -738,6 +739,7 @@ export async function updateSessionLastRoute(params: {
     {
       // Route updates must not refresh activity timestamps (#49515).
       preserveActivity: true,
+      ...(params.assertCommitAllowed ? { assertCommitAllowed: params.assertCommitAllowed } : {}),
       ...(createIfMissing ? { fallbackEntry: mergeSessionEntry(undefined, {}) } : {}),
     },
   );
diff --git a/src/config/sessions/session-accessor.sqlite-lifecycle-state.ts b/src/config/sessions/session-accessor.sqlite-lifecycle-state.ts
index c3e7bc0a3aa1..803b0030f7a6 100644
--- a/src/config/sessions/session-accessor.sqlite-lifecycle-state.ts
+++ b/src/config/sessions/session-accessor.sqlite-lifecycle-state.ts
@@ -405,6 +405,7 @@ export async function projectSessionEntryLifecycleMutation(
       expectedEntry,
       sessionKey,
       entry: cloned,
+      ...(upsert.routeContext !== undefined ? { routeContext: upsert.routeContext } : {}),
       ...(resetBoundaryPlan ? { resetBoundaryPlan } : {}),
     });
   }
diff --git a/src/config/sessions/session-accessor.sqlite-lifecycle-types.ts b/src/config/sessions/session-accessor.sqlite-lifecycle-types.ts
index 8256307f28d8..45fccb08d7b0 100644
--- a/src/config/sessions/session-accessor.sqlite-lifecycle-types.ts
+++ b/src/config/sessions/session-accessor.sqlite-lifecycle-types.ts
@@ -1,3 +1,4 @@
+import type { ConversationRouteContext } from "./conversation-route-context.js";
 import type { SessionLifecycleArchivedTranscript } from "./session-accessor.lifecycle-types.js";
 import type { SessionStateDeletePlan } from "./session-accessor.sqlite-archive.js";
 import type { SessionEntryLifecycleRemoval } from "./session-accessor.sqlite-contract.js";
@@ -37,6 +38,7 @@ export type ProjectedLifecycleMutation = {
   upsertedEntries: Array<{
     entry: SessionEntry;
     expectedEntry: SessionEntry | undefined;
+    routeContext?: ConversationRouteContext | null;
     resetBoundaryPlan?: SessionResetBoundaryPlan;
     sessionKey: string;
   }>;
diff --git a/src/config/sessions/session-accessor.sqlite-projection.ts b/src/config/sessions/session-accessor.sqlite-projection.ts
index 952c1ef53c9d..c7be6899fe17 100644
--- a/src/config/sessions/session-accessor.sqlite-projection.ts
+++ b/src/config/sessions/session-accessor.sqlite-projection.ts
@@ -339,6 +339,7 @@ export async function applySessionEntryLifecycleMutation(params: {
         sessionKey,
         entry,
         expectedEntry,
+        routeContext,
         resetBoundaryPlan,
       } of projected.upsertedEntries) {
         const sameKeyRemoval = validatedRemovals.find(
@@ -377,6 +378,7 @@ export async function applySessionEntryLifecycleMutation(params: {
           allowStoredAliases: params.allowCanonicalRepair === true,
           preserveNodeSuggestions: params.allowCanonicalRepair === true,
           previousEntry: expectedCurrentEntry ?? null,
+          ...(routeContext !== undefined ? { routeContext } : {}),
         });
         const relatedRemovalKeys = validatedRemovals.flatMap((removal) => {
           const removedSessionId = removal.expectedEntry.sessionId;
diff --git a/src/config/sessions/session-accessor.test.ts b/src/config/sessions/session-accessor.test.ts
index bd35f1cfbf9e..1f61a3af75e9 100644
--- a/src/config/sessions/session-accessor.test.ts
+++ b/src/config/sessions/session-accessor.test.ts
@@ -839,6 +839,24 @@ describe("session accessor seam", () => {
     expect(loadSessionEntry({ sessionKey, storePath })).toBeUndefined();
   });
 
+  it("runs the last-route ownership guard at the SQLite commit edge", async () => {
+    const sessionKey = "agent:main:webchat:dm:revoked-route";
+
+    await expect(
+      updateSessionLastRoute({
+        storePath,
+        sessionKey,
+        channel: "webchat",
+        to: "webchat:revoked-route",
+        assertCommitAllowed: () => {
+          throw new Error("route owner changed");
+        },
+      }),
+    ).rejects.toThrow("route owner changed");
+
+    expect(loadSessionEntry({ sessionKey, storePath })).toBeUndefined();
+  });
+
   it("stamps last-route creation from the participant, never the conversation route", async () => {
     const participantKey = "agent:main:webchat:dm:route-participant";
     const participant = await updateSessionLastRoute({
diff --git a/src/gateway/conversation-list.test.ts b/src/gateway/conversation-list.test.ts
index b144c902f0dc..3ca6af0b23e0 100644
--- a/src/gateway/conversation-list.test.ts
+++ b/src/gateway/conversation-list.test.ts
@@ -3,6 +3,127 @@ import type { ConversationIdentity } from "../config/sessions/conversation-ident
 import { runGatewayConversationList } from "./conversation-list.js";
 
 describe("runGatewayConversationList", () => {
+  it("discovers only routes owned by the active agent", async () => {
+    let discovered: ConversationIdentity[] = [];
+    const deps = {
+      resolveOutboundChannelPlugin: vi.fn(() => ({
+        id: "reef",
+        config: {
+          listAccountIds: () => ["personal", "finance"],
+          resolveAccount: () => ({ enabled: true, configured: true }),
+          isEnabled: () => true,
+          isConfigured: () => true,
+        },
+        directory: {
+          listPeers: async ({ accountId }: { accountId: string }) => [
+            { kind: "user" as const, id: `${accountId}-peer`, name: accountId },
+          ],
+        },
+      })),
+      resolveOutboundSessionRoute: vi.fn(async ({ target }: { target: string }) => ({
+        sessionKey: `agent:personal:reef:direct:${target}`,
+        baseSessionKey: `agent:personal:reef:direct:${target}`,
+        peer: { kind: "direct" as const, id: target },
+        chatType: "direct" as const,
+        from: `reef:${target}`,
+        to: `reef:${target}`,
+      })),
+      registerConversationAddresses: vi.fn((_scope, identities) => {
+        discovered = [...identities];
+      }),
+      listConversations: vi.fn(() => []),
+    };
+
+    await runGatewayConversationList(
+      {
+        config: {
+          agents: { entries: { personal: {}, finance: {} } },
+          bindings: [
+            {
+              type: "route",
+              agentId: "personal",
+              match: { channel: "reef", accountId: "personal" },
+            },
+            {
+              type: "route",
+              agentId: "finance",
+              match: { channel: "reef", accountId: "finance" },
+            },
+          ],
+        },
+        agentId: "personal",
+        channel: "reef",
+        limit: 50,
+      },
+      deps as never,
+    );
+
+    expect(discovered).toEqual([
+      expect.objectContaining({ accountId: "personal", peerId: "personal-peer" }),
+    ]);
+  });
+
+  it("filters persisted routes before applying the result limit", async () => {
+    const rows = [
+      {
+        conversationRef: "conv_11111111111111111111111111111111",
+        channel: "reef",
+        accountId: "finance",
+        kind: "direct" as const,
+        peerId: "finance-peer",
+        target: "reef:finance-peer",
+        firstSeenAt: 200,
+        lastSeenAt: 200,
+      },
+      {
+        conversationRef: "conv_22222222222222222222222222222222",
+        channel: "reef",
+        accountId: "personal",
+        kind: "direct" as const,
+        peerId: "personal-peer",
+        target: "reef:personal-peer",
+        firstSeenAt: 100,
+        lastSeenAt: 100,
+      },
+    ];
+    const listConversations = vi.fn((_scope, options: { limit?: number }) =>
+      options.limit === undefined ? rows : rows.slice(0, options.limit),
+    );
+
+    const result = await runGatewayConversationList(
+      {
+        config: {
+          agents: { entries: { personal: {}, finance: {} } },
+          bindings: [
+            {
+              type: "route",
+              agentId: "personal",
+              match: { channel: "reef", accountId: "personal" },
+            },
+            {
+              type: "route",
+              agentId: "finance",
+              match: { channel: "reef", accountId: "finance" },
+            },
+          ],
+        },
+        agentId: "personal",
+        limit: 1,
+      },
+      {
+        listConversations,
+        registerConversationAddresses: vi.fn(),
+        resolveOutboundChannelPlugin: vi.fn(),
+        resolveOutboundSessionRoute: vi.fn(),
+      } as never,
+    );
+
+    expect(listConversations).toHaveBeenCalledWith({ agentId: "personal" }, {});
+    expect(result.conversations).toEqual([
+      expect.objectContaining({ accountId: "personal", target: "reef:personal-peer" }),
+    ]);
+  });
+
   it("discovers a trusted directory peer without creating a session", async () => {
     let discovered: ConversationIdentity[] = [];
     const listPeers = vi.fn(async () => [
@@ -37,6 +158,7 @@ describe("runGatewayConversationList", () => {
           channel: identity.channel,
           accountId: identity.accountId,
           kind: identity.kind,
+          peerId: identity.peerId,
           target: identity.deliveryTarget,
           label: identity.label,
           firstSeenAt: 100,
diff --git a/src/gateway/conversation-list.ts b/src/gateway/conversation-list.ts
index 6f3def8298bb..8105675cfaa8 100644
--- a/src/gateway/conversation-list.ts
+++ b/src/gateway/conversation-list.ts
@@ -20,6 +20,7 @@ import { resolveOutboundChannelPlugin } from "../infra/outbound/channel-resoluti
 import { resolveOutboundSessionRoute } from "../infra/outbound/outbound-session.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import { defaultRuntime } from "../runtime.js";
+import { resolveConversationRouteEligibilityForAgent } from "./conversation-route-ownership.js";
 
 const log = createSubsystemLogger("gateway/conversations");
 
@@ -124,6 +125,7 @@ async function discoverChannelAddresses(params: {
   limit: number;
   scope: ConversationRegistryScope;
   deps: ConversationListDeps;
+  readCurrentConfig?: () => OpenClawConfig;
 }): Promise<{ channel: string; discoveredConversationRefs: ReadonlySet<string> }> {
   const plugin = params.deps.resolveOutboundChannelPlugin({
     channel: params.channel,
@@ -193,8 +195,25 @@ async function discoverChannelAddresses(params: {
       }
     }
   }
-  params.deps.registerConversationAddresses(params.scope, [...identities.values()]);
-  return { channel: plugin.id, discoveredConversationRefs: new Set(identities.keys()) };
+  const currentConfig = params.readCurrentConfig?.() ?? params.config;
+  const eligibleIdentities = [...identities.values()].filter((identity) => {
+    const eligibility = resolveConversationRouteEligibilityForAgent({
+      config: currentConfig,
+      agentId: params.agentId,
+      conversation: { ...identity, target: identity.deliveryTarget },
+    });
+    if (eligibility === "unavailable") {
+      throw new Error("Conversation route ownership is temporarily unavailable");
+    }
+    return eligibility === "eligible";
+  });
+  params.deps.registerConversationAddresses(params.scope, eligibleIdentities);
+  return {
+    channel: plugin.id,
+    discoveredConversationRefs: new Set(
+      eligibleIdentities.map((identity) => identity.conversationRef),
+    ),
+  };
 }
 
 function matchesConversationQuery(conversation: ConversationRecord, rawQuery: string): boolean {
@@ -213,6 +232,7 @@ function matchesConversationQuery(conversation: ConversationRecord, rawQuery: st
 export async function runGatewayConversationList(
   params: {
     config: OpenClawConfig;
+    readCurrentConfig?: () => OpenClawConfig;
     agentId: string;
     channel?: string;
     query?: string;
@@ -231,20 +251,33 @@ export async function runGatewayConversationList(
         limit: params.limit,
         scope,
         deps,
+        ...(params.readCurrentConfig ? { readCurrentConfig: params.readCurrentConfig } : {}),
       })
     : undefined;
-  const conversations = deps.listConversations(scope, {
-    ...(query ? {} : { limit: params.limit }),
-    ...(discovery ? { channel: discovery.channel } : {}),
-  });
-  const selected = query
-    ? conversations
-        .filter(
-          (entry) =>
-            discovery?.discoveredConversationRefs.has(entry.conversationRef) === true ||
-            matchesConversationQuery(entry, query),
-        )
-        .slice(0, params.limit)
-    : conversations;
+  const conversations = deps.listConversations(
+    scope,
+    discovery ? { channel: discovery.channel } : {},
+  );
+  const currentConfig = params.readCurrentConfig?.() ?? params.config;
+  const selected = conversations
+    .filter((entry) => {
+      if (
+        query &&
+        discovery?.discoveredConversationRefs.has(entry.conversationRef) !== true &&
+        !matchesConversationQuery(entry, query)
+      ) {
+        return false;
+      }
+      const eligibility = resolveConversationRouteEligibilityForAgent({
+        config: currentConfig,
+        agentId: params.agentId,
+        conversation: entry,
+      });
+      if (eligibility === "unavailable") {
+        throw new Error("Conversation route ownership is temporarily unavailable");
+      }
+      return eligibility === "eligible";
+    })
+    .slice(0, params.limit);
   return { conversations: selected.map(presentConversation) };
 }
diff --git a/src/gateway/conversation-route-ownership.test.ts b/src/gateway/conversation-route-ownership.test.ts
new file mode 100644
index 000000000000..abc75e65da25
--- /dev/null
+++ b/src/gateway/conversation-route-ownership.test.ts
@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import type { OpenClawConfig } from "../config/types.openclaw.js";
+import { resolveConversationRouteEligibilityForAgent } from "./conversation-route-ownership.js";
+
+const baseConversation = {
+  accountId: "default",
+  channel: "reef",
+  kind: "group" as const,
+  peerId: "topic-42",
+  target: "group:topic-42",
+};
+
+function configWithBindings(bindings: NonNullable<OpenClawConfig["bindings"]>): OpenClawConfig {
+  return {
+    agents: { entries: { main: { default: true }, finance: {} } },
+    bindings,
+  };
+}
+
+describe("resolveConversationRouteEligibilityForAgent", () => {
+  it("replays authoritative parent context when selecting the route owner", () => {
+    const config = configWithBindings([
+      {
+        type: "route",
+        agentId: "finance",
+        match: { channel: "reef", peer: { kind: "group", id: "parent-room" } },
+      },
+    ]);
+    const conversation = {
+      ...baseConversation,
+      routeContextObserved: true as const,
+      routeContext: { parentPeerId: "parent-room" },
+    };
+
+    expect(
+      resolveConversationRouteEligibilityForAgent({ config, agentId: "main", conversation }),
+    ).toBe("denied");
+    expect(
+      resolveConversationRouteEligibilityForAgent({ config, agentId: "finance", conversation }),
+    ).toBe("eligible");
+  });
+
+  it("does not treat an unrelated peer binding as a possible parent owner for a legacy thread", () => {
+    const config = configWithBindings([
+      {
+        type: "route",
+        agentId: "finance",
+        match: { channel: "reef", peer: { kind: "group", id: "unrelated-room" } },
+      },
+    ]);
+
+    expect(
+      resolveConversationRouteEligibilityForAgent({
+        config,
+        agentId: "main",
+        conversation: { ...baseConversation, threadId: "topic-7" },
+      }),
+    ).toBe("eligible");
+  });
+
+  it("replays a legacy thread parent binding from its retained route peer", () => {
+    const config = configWithBindings([
+      {
+        type: "route",
+        agentId: "finance",
+        match: { channel: "reef", peer: { kind: "group", id: "parent-room" } },
+      },
+    ]);
+    const conversation = { ...baseConversation, peerId: "parent-room", threadId: "topic-7" };
+
+    expect(
+      resolveConversationRouteEligibilityForAgent({ config, agentId: "main", conversation }),
+    ).toBe("denied");
+    expect(
+      resolveConversationRouteEligibilityForAgent({ config, agentId: "finance", conversation }),
+    ).toBe("eligible");
+  });
+
+  it("fails closed for a matching contextual wildcard when legacy context is absent", () => {
+    const config = configWithBindings([
+      {
+        type: "route",
+        agentId: "finance",
+        match: { channel: "reef", peer: { kind: "group", id: "*" }, teamId: "finance" },
+      },
+    ]);
+
+    expect(
+      resolveConversationRouteEligibilityForAgent({
+        config,
+        agentId: "main",
+        conversation: baseConversation,
+      }),
+    ).toBe("denied");
+
+    expect(
+      resolveConversationRouteEligibilityForAgent({
+        config,
+        agentId: "main",
+        conversation: { ...baseConversation, routeContextObserved: true },
+      }),
+    ).toBe("eligible");
+  });
+});
diff --git a/src/gateway/conversation-route-ownership.ts b/src/gateway/conversation-route-ownership.ts
new file mode 100644
index 000000000000..b8df52b5a079
--- /dev/null
+++ b/src/gateway/conversation-route-ownership.ts
@@ -0,0 +1,354 @@
+import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
+import { AgentSelectionRequiredError } from "../agents/agent-scope-config.js";
+import { normalizeChatType } from "../channels/chat-type.js";
+import {
+  resolveConfiguredBindingRoute,
+  resolveRuntimeConversationBindingRoute,
+} from "../channels/plugins/binding-routing.js";
+import { getLoadedChannelPlugin, normalizeChannelId } from "../channels/plugins/index.js";
+import { listRouteBindings } from "../config/bindings.js";
+import { getConversationDeliveryOperation } from "../config/sessions/conversation-delivery-store.js";
+import {
+  resolveConversation,
+  type ConversationRecord,
+  type ConversationRegistryScope,
+} from "../config/sessions/conversation-registry.js";
+import type { ConversationRouteContext } from "../config/sessions/conversation-route-context.js";
+import { resolveConversationRouteFingerprint } from "../config/sessions/conversation-route-fingerprint.js";
+import type { OpenClawConfig } from "../config/types.openclaw.js";
+import { PlatformMessageNotDispatchedError } from "../infra/outbound/deliver-types.js";
+import { getGlobalPluginRegistry } from "../plugins/hook-runner-global.js";
+import { normalizeAccountId } from "../routing/account-id.js";
+import { normalizeRouteBindingId } from "../routing/binding-scope.js";
+import { peerKindMatches } from "../routing/peer-kind-match.js";
+import { resolveAgentRoute, type ResolvedAgentRoute } from "../routing/resolve-route.js";
+import { normalizeAgentId } from "../routing/session-key.js";
+import { ConversationInputError } from "./conversation-errors.js";
+
+type ConversationRouteCandidate = Pick<
+  ConversationRecord,
+  "accountId" | "channel" | "kind" | "parentConversationRef" | "peerId" | "target" | "threadId"
+> & {
+  nativeChannelId?: string;
+  routeContext?: ConversationRouteContext;
+  routeContextObserved?: true;
+};
+
+type ConversationRouteEligibility = "eligible" | "denied" | "unavailable";
+
+type RouteOwnerResolution = { kind: "available"; agentId?: string } | { kind: "unavailable" };
+
+function hasActivePluginClaimOwner(pluginId: string): boolean {
+  return (
+    getGlobalPluginRegistry()?.typedHooks.some(
+      (hook) => hook.pluginId === pluginId && hook.hookName === "inbound_claim",
+    ) === true
+  );
+}
+
+function resolvePluginRouteOwner(
+  config: OpenClawConfig,
+  conversation: ConversationRouteCandidate,
+): RouteOwnerResolution | undefined {
+  const channelId = normalizeChannelId(conversation.channel);
+  const resolver = channelId
+    ? getLoadedChannelPlugin(channelId)?.messaging?.resolveConversationRouteOwner
+    : undefined;
+  if (!resolver) {
+    return undefined;
+  }
+  try {
+    const owner = resolver({
+      cfg: config,
+      accountId: normalizeAccountId(conversation.accountId),
+      conversation: {
+        kind: conversation.kind,
+        peerId: conversation.peerId,
+        target: conversation.target,
+        ...(conversation.threadId ? { threadId: conversation.threadId } : {}),
+        ...(conversation.nativeChannelId ? { nativeChannelId: conversation.nativeChannelId } : {}),
+        ...(conversation.routeContext ? { context: conversation.routeContext } : {}),
+      },
+    });
+    if (owner === undefined) {
+      return undefined;
+    }
+    if (owner === null) {
+      return { kind: "available" };
+    }
+    if (owner.kind === "unavailable") {
+      return owner;
+    }
+    if (owner.kind === "plugin") {
+      return hasActivePluginClaimOwner(owner.pluginId)
+        ? { kind: "available" }
+        : { kind: "available", agentId: normalizeAgentId(owner.fallbackAgentId) };
+    }
+    return { kind: "available", agentId: normalizeAgentId(owner.agentId) };
+  } catch (error) {
+    if (error instanceof AgentSelectionRequiredError) {
+      return { kind: "available" };
+    }
+    throw error;
+  }
+}
+
+function resolveConfiguredRouteOwner(
+  config: OpenClawConfig,
+  conversation: ConversationRouteCandidate,
+  context?: ConversationRouteContext,
+): ResolvedAgentRoute | undefined {
+  try {
+    return resolveAgentRoute({
+      cfg: config,
+      channel: conversation.channel,
+      accountId: conversation.accountId,
+      peer: { kind: conversation.kind, id: conversation.peerId },
+      ...(context?.parentPeerId && conversation.kind !== "direct"
+        ? { parentPeer: { kind: conversation.kind, id: context.parentPeerId } }
+        : {}),
+      ...(context?.guildId ? { guildId: context.guildId } : {}),
+      ...(context?.teamId ? { teamId: context.teamId } : {}),
+      ...(context?.memberRoleIds ? { memberRoleIds: context.memberRoleIds } : {}),
+    });
+  } catch (error) {
+    if (error instanceof AgentSelectionRequiredError) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+function resolveGenericRouteOwner(params: {
+  config: OpenClawConfig;
+  conversation: ConversationRouteCandidate;
+  route: ResolvedAgentRoute;
+  context?: ConversationRouteContext;
+}): RouteOwnerResolution {
+  const conversation = {
+    channel: params.conversation.channel,
+    accountId: normalizeAccountId(params.conversation.accountId),
+    conversationId: params.conversation.peerId,
+    ...(params.context?.parentPeerId ? { parentConversationId: params.context.parentPeerId } : {}),
+  };
+  // Generic ingress applies configured ACP routing before runtime bindings. Discord and Slack
+  // have different precedence and bypass this path through their channel-owned resolvers.
+  const configured = resolveConfiguredBindingRoute({
+    cfg: params.config,
+    route: params.route,
+    conversation,
+  });
+  const runtime = resolveRuntimeConversationBindingRoute({
+    route: configured.route,
+    conversation,
+    touchBinding: false,
+  });
+  if (runtime.bindingOwnerAvailable === false) {
+    return { kind: "unavailable" };
+  }
+  if (runtime.pluginId && hasActivePluginClaimOwner(runtime.pluginId)) {
+    return { kind: "available" };
+  }
+  return { kind: "available", agentId: normalizeAgentId(runtime.route.agentId) };
+}
+
+function bindingPeerCouldMatchConversation(
+  binding: ReturnType<typeof listRouteBindings>[number],
+  conversation: ConversationRouteCandidate,
+): boolean {
+  // Before routePeer persistence, migration derived peerId from the delivery target, so topic
+  // rows retain their parent chat there. Current child peers always carry observed parent context.
+  // Treating every same-kind peer as a possible parent would let unrelated bindings deny valid routes.
+  const peer = binding.match.peer;
+  if (!peer) {
+    return true;
+  }
+  const kind = normalizeChatType(peer.kind);
+  const id = normalizeRouteBindingId(peer.id);
+  if (!kind || !id) {
+    return false;
+  }
+  return peerKindMatches(kind, conversation.kind) && (id === "*" || id === conversation.peerId);
+}
+
+function hasUnrecordedContextualBinding(params: {
+  config: OpenClawConfig;
+  conversation: ConversationRouteCandidate;
+  resolvedAgentId: string;
+}): boolean {
+  const channel = normalizeLowercaseStringOrEmpty(params.conversation.channel);
+  const accountId = normalizeAccountId(params.conversation.accountId);
+  const hasThreadContext = Boolean(
+    params.conversation.parentConversationRef || params.conversation.threadId,
+  );
+  const hasGuildContext = params.conversation.kind === "channel";
+  return listRouteBindings(params.config).some((binding) => {
+    const pattern = binding.match.accountId?.trim() ?? "";
+    const contextualScope = Boolean(
+      (hasGuildContext && normalizeRouteBindingId(binding.match.guildId)) ||
+      normalizeRouteBindingId(binding.match.teamId) ||
+      (hasGuildContext && binding.match.roles?.length) ||
+      (hasThreadContext &&
+        binding.match.peer?.kind !== "direct" &&
+        normalizeRouteBindingId(binding.match.peer?.id)),
+    );
+    return (
+      contextualScope &&
+      normalizeAgentId(binding.agentId) !== params.resolvedAgentId &&
+      normalizeLowercaseStringOrEmpty(binding.match.channel) === channel &&
+      (pattern === "*" || normalizeAccountId(pattern) === accountId) &&
+      bindingPeerCouldMatchConversation(binding, params.conversation)
+    );
+  });
+}
+
+/** Replays current configured and plugin-owned routing for a persisted conversation address. */
+export function resolveConversationRouteEligibilityForAgent(params: {
+  config: OpenClawConfig;
+  agentId: string;
+  conversation: ConversationRouteCandidate;
+}): ConversationRouteEligibility {
+  const requestedAgentId = normalizeAgentId(params.agentId);
+  const hasObservedContext = Boolean(
+    params.conversation.routeContextObserved || params.conversation.routeContext,
+  );
+  const pluginOwner = resolvePluginRouteOwner(params.config, params.conversation);
+  if (pluginOwner) {
+    if (pluginOwner.kind === "unavailable") {
+      return "unavailable";
+    }
+    return pluginOwner.agentId === requestedAgentId &&
+      !(
+        !hasObservedContext &&
+        pluginOwner.agentId &&
+        hasUnrecordedContextualBinding({
+          config: params.config,
+          conversation: params.conversation,
+          resolvedAgentId: pluginOwner.agentId,
+        })
+      )
+      ? "eligible"
+      : "denied";
+  }
+
+  const route = resolveConfiguredRouteOwner(
+    params.config,
+    params.conversation,
+    params.conversation.routeContext,
+  );
+  if (!route) {
+    return "denied";
+  }
+  const owner = resolveGenericRouteOwner({
+    config: params.config,
+    conversation: params.conversation,
+    route,
+    ...(params.conversation.routeContext ? { context: params.conversation.routeContext } : {}),
+  });
+  if (owner.kind === "unavailable") {
+    return "unavailable";
+  }
+  if (owner.agentId !== requestedAgentId) {
+    return "denied";
+  }
+  return !hasObservedContext &&
+    hasUnrecordedContextualBinding({
+      config: params.config,
+      conversation: params.conversation,
+      resolvedAgentId: owner.agentId,
+    })
+    ? "denied"
+    : "eligible";
+}
+
+/** Enforces current route ownership at a Gateway request boundary. */
+export function assertConversationRouteEligibleForAgent(params: {
+  config: OpenClawConfig;
+  agentId: string;
+  conversation: ConversationRouteCandidate & Pick<ConversationRecord, "conversationRef">;
+}): void {
+  const eligibility = resolveConversationRouteEligibilityForAgent(params);
+  if (eligibility === "eligible") {
+    return;
+  }
+  if (eligibility === "denied") {
+    throw new ConversationInputError(
+      `Conversation is not available to this agent: ${params.conversation.conversationRef}`,
+    );
+  }
+  throw new Error(
+    `Conversation ownership is temporarily unavailable: ${params.conversation.conversationRef}`,
+  );
+}
+
+type ResolveConversation = typeof resolveConversation;
+
+export function assertConversationDeliveryAttemptAuthorized(params: {
+  config: OpenClawConfig;
+  agentId: string;
+  conversationRef: string;
+  expectedRouteFingerprint: string;
+  expectedSessionId?: string;
+  expectedSessionKey?: string;
+  scope: ConversationRegistryScope;
+  resolveConversation?: ResolveConversation;
+}): void {
+  const conversation = (params.resolveConversation ?? resolveConversation)(
+    params.scope,
+    params.conversationRef,
+  );
+  if (
+    !conversation ||
+    resolveConversationRouteFingerprint(conversation) !== params.expectedRouteFingerprint ||
+    (params.expectedSessionId !== undefined &&
+      conversation.sessionId !== params.expectedSessionId) ||
+    (params.expectedSessionKey !== undefined &&
+      conversation.sessionKey !== params.expectedSessionKey)
+  ) {
+    throw new PlatformMessageNotDispatchedError(
+      `Conversation is no longer available to this agent: ${params.conversationRef}`,
+      { cause: undefined, retryable: false },
+    );
+  }
+  const eligibility = resolveConversationRouteEligibilityForAgent({
+    config: params.config,
+    agentId: params.agentId,
+    conversation,
+  });
+  if (eligibility === "eligible") {
+    return;
+  }
+  throw new PlatformMessageNotDispatchedError(
+    eligibility === "unavailable"
+      ? `Conversation ownership is temporarily unavailable: ${params.conversationRef}`
+      : `Conversation is no longer available to this agent: ${params.conversationRef}`,
+    { cause: undefined, retryable: eligibility === "unavailable" },
+  );
+}
+
+export function assertQueuedConversationDeliveryAttemptAuthorized(params: {
+  config: OpenClawConfig;
+  agentId: string;
+  operationId: string;
+  storePath?: string;
+  routeFingerprint: string;
+}): void {
+  const scope = {
+    agentId: params.agentId,
+    ...(params.storePath ? { storePath: params.storePath } : {}),
+  };
+  const operation = getConversationDeliveryOperation(scope, params.operationId);
+  if (!operation) {
+    throw new PlatformMessageNotDispatchedError(
+      `Conversation delivery operation no longer exists: ${params.operationId}`,
+      { cause: undefined, retryable: false },
+    );
+  }
+  assertConversationDeliveryAttemptAuthorized({
+    config: params.config,
+    agentId: params.agentId,
+    conversationRef: operation.conversationRef,
+    expectedRouteFingerprint: params.routeFingerprint,
+    scope,
+  });
+}
diff --git a/src/gateway/conversation-send.test.ts b/src/gateway/conversation-send.test.ts
index 9e4f8b699730..ed902905bb96 100644
--- a/src/gateway/conversation-send.test.ts
+++ b/src/gateway/conversation-send.test.ts
@@ -15,6 +15,7 @@ const conversation = {
   channel: "reef",
   accountId: "default",
   kind: "direct" as const,
+  peerId: "molty",
   target: "reef:molty",
   sessionId: "reef-session",
   sessionKey: "agent:main:reef:direct:molty",
@@ -190,8 +191,6 @@ describe("runGatewayConversationSend", () => {
       createdAt: 100,
       updatedAt: 200,
     });
-    deps.resolveConversation.mockReturnValue(undefined);
-
     await expect(
       runGatewayConversationSend(
         {
@@ -205,10 +204,128 @@ describe("runGatewayConversationSend", () => {
         deps,
       ),
     ).resolves.toMatchObject({ status: "sent", messageId: "reef-existing" });
-    expect(deps.resolveConversation).not.toHaveBeenCalled();
+    expect(deps.resolveConversation).toHaveBeenCalled();
     expect(deps.runMessageAction).not.toHaveBeenCalled();
   });
 
+  it("does not reveal completed send state after the route owner changes", async () => {
+    const deps = createDeps();
+    deps.operations.set("send-reassigned", {
+      operationId: "send-reassigned",
+      operationKind: "send",
+      conversationRef: conversation.conversationRef,
+      channel: conversation.channel,
+      messageHash: "hello",
+      status: "sent",
+      platformMessageId: "reef-private-message",
+      createdAt: 100,
+      updatedAt: 200,
+    });
+
+    await expect(
+      runGatewayConversationSend(
+        {
+          config: {
+            agents: { entries: { main: {}, finance: {} } },
+            bindings: [
+              {
+                type: "route",
+                agentId: "finance",
+                match: { channel: "reef", accountId: "default" },
+              },
+            ],
+          },
+          agentId: "main",
+          senderIsOwner: true,
+          operationId: "send-reassigned",
+          conversationRef: conversation.conversationRef,
+          message: "hello",
+        },
+        deps,
+      ),
+    ).rejects.toBeInstanceOf(ConversationInputError);
+  });
+
+  it("rejects a stored conversation route owned by another agent", async () => {
+    const deps = createDeps();
+
+    await expect(
+      runGatewayConversationSend(
+        {
+          config: {
+            agents: { entries: { main: {}, finance: {} } },
+            bindings: [
+              {
+                type: "route",
+                agentId: "finance",
+                match: { channel: "reef", accountId: "default" },
+              },
+            ],
+          },
+          agentId: "main",
+          senderIsOwner: true,
+          operationId: "send-sibling-route",
+          conversationRef: conversation.conversationRef,
+          message: "hello",
+        },
+        deps,
+      ),
+    ).rejects.toBeInstanceOf(ConversationInputError);
+    expect(deps.beginOperation).not.toHaveBeenCalled();
+    expect(deps.runMessageAction).not.toHaveBeenCalled();
+  });
+
+  it("revalidates a route-owner change at the durable delivery attempt", async () => {
+    const deps = createDeps();
+    deps.runMessageAction = vi.fn(async (input: Record<string, unknown>) => {
+      const onDeliveryIntent = input.onDeliveryIntent as (intent: {
+        id: string;
+        channel: string;
+        to: string;
+        durability: "required";
+      }) => void;
+      onDeliveryIntent({
+        id: "queue-revoked-route",
+        channel: "reef",
+        to: "molty",
+        durability: "required",
+      });
+      await (input.onDeliveryAttempt as () => Promise<void>)();
+      return sentResult();
+    }) as never;
+    const readCurrentConfig = vi
+      .fn()
+      .mockReturnValueOnce({})
+      .mockReturnValue({
+        agents: { entries: { main: {}, finance: {} } },
+        bindings: [
+          {
+            type: "route",
+            agentId: "finance",
+            match: { channel: "reef", accountId: "default" },
+          },
+        ],
+      });
+
+    await expect(
+      runGatewayConversationSend(
+        {
+          config: {},
+          readCurrentConfig,
+          agentId: "main",
+          senderIsOwner: true,
+          operationId: "send-revoked-route",
+          conversationRef: conversation.conversationRef,
+          message: "hello",
+        },
+        deps,
+      ),
+    ).resolves.toMatchObject({ status: "queued", queueId: "queue-revoked-route" });
+
+    expect(readCurrentConfig).toHaveBeenCalledTimes(2);
+    expect(deps.markSent).not.toHaveBeenCalled();
+  });
+
   it("namespaces stable queue intents across agents", async () => {
     const mainDeps = createDeps();
     const workerDeps = createDeps();
@@ -226,7 +343,9 @@ describe("runGatewayConversationSend", () => {
     );
     await runGatewayConversationSend(
       {
-        config: {},
+        config: {
+          agents: { entries: { worker: { default: true } } },
+        },
         agentId: "worker",
         senderIsOwner: true,
         operationId: "shared-operation",
diff --git a/src/gateway/conversation-send.ts b/src/gateway/conversation-send.ts
index 6a0a280c62e8..d4016be48cae 100644
--- a/src/gateway/conversation-send.ts
+++ b/src/gateway/conversation-send.ts
@@ -7,6 +7,7 @@ import {
   resolveConversation,
   resolveConversationRegistryScope,
 } from "../config/sessions/conversation-registry.js";
+import { resolveConversationRouteFingerprint } from "../config/sessions/conversation-route-fingerprint.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
   ConversationDeliveryRejectedError,
@@ -18,6 +19,10 @@ import {
   ConversationInputError,
   ConversationOperationConflictError,
 } from "./conversation-errors.js";
+import {
+  assertConversationDeliveryAttemptAuthorized,
+  assertConversationRouteEligibleForAgent,
+} from "./conversation-route-ownership.js";
 
 type ConversationSendDeps = ConversationDeliveryDeps & {
   resolveConversation: typeof resolveConversation;
@@ -70,6 +75,7 @@ function resultForCompletedOperation(
 export async function runGatewayConversationSend(
   params: {
     config: OpenClawConfig;
+    readCurrentConfig?: () => OpenClawConfig;
     agentId: string;
     senderIsOwner: boolean;
     sourceSessionKey?: string;
@@ -92,10 +98,6 @@ export async function runGatewayConversationSend(
         ...(params.sourceSessionKey ? { sourceSessionKey: params.sourceSessionKey } : {}),
         message: params.message,
       }).record;
-      const completed = resultForCompletedOperation(operation);
-      if (completed) {
-        return completed;
-      }
     }
 
     const conversation = deps.resolveConversation(scope, params.conversationRef);
@@ -104,18 +106,42 @@ export async function runGatewayConversationSend(
         `Conversation not found: ${params.conversationRef} (use conversations_list)`,
       );
     }
+    const currentConfig = params.readCurrentConfig?.() ?? params.config;
+    assertConversationRouteEligibleForAgent({
+      config: currentConfig,
+      agentId: params.agentId,
+      conversation,
+    });
+    const routeFingerprint = resolveConversationRouteFingerprint(conversation);
+    if (operation) {
+      const completed = resultForCompletedOperation(operation);
+      if (completed) {
+        return completed;
+      }
+    }
     const sent = await sendGatewayConversationMessage({
       deps,
       context: {
         agentId: params.agentId,
         ...(params.sourceSessionKey ? { sourceSessionKey: params.sourceSessionKey } : {}),
-        config: params.config,
+        config: currentConfig,
         senderIsOwner: params.senderIsOwner,
       },
       conversation,
       message: params.message,
       operationId: params.operationId,
       operationKind: "send",
+      routeFingerprint,
+      onDeliveryAttempt: async () => {
+        assertConversationDeliveryAttemptAuthorized({
+          config: params.readCurrentConfig?.() ?? currentConfig,
+          agentId: params.agentId,
+          conversationRef: conversation.conversationRef,
+          expectedRouteFingerprint: routeFingerprint,
+          scope,
+          resolveConversation: deps.resolveConversation,
+        });
+      },
       ...(operation ? { operation } : {}),
       ...(params.signal ? { signal: params.signal } : {}),
     });
diff --git a/src/gateway/conversation-turn.test.ts b/src/gateway/conversation-turn.test.ts
index 004f67f97e92..c6a0813d8aa1 100644
--- a/src/gateway/conversation-turn.test.ts
+++ b/src/gateway/conversation-turn.test.ts
@@ -18,6 +18,7 @@ const conversation = {
   channel: "reef",
   accountId: "default",
   kind: "direct" as const,
+  peerId: "molty",
   target: "reef:molty",
   sessionId: "reef-session",
   sessionKey: "agent:main:reef:direct:molty",
@@ -136,7 +137,9 @@ function createDeps() {
       from: "reef:molty",
       to: conversation.target,
     })),
-    bindOutboundSessionEntry: vi.fn(async () => undefined),
+    bindOutboundSessionEntry: vi.fn(
+      async (_params: { assertCommitAllowed?: () => void }) => undefined,
+    ),
     runMessageAction: vi.fn(async () => sentResult()) as never,
     operations,
     update,
@@ -159,6 +162,37 @@ function persistIntent(input: Record<string, unknown>): void {
 }
 
 describe("runGatewayConversationTurn", () => {
+  it("rejects a stored conversation route owned by another agent", async () => {
+    const deps = createDeps();
+
+    await expect(
+      runGatewayConversationTurn(
+        {
+          config: {
+            agents: { entries: { main: {}, finance: {} } },
+            bindings: [
+              {
+                type: "route",
+                agentId: "finance",
+                match: { channel: "reef", accountId: "default" },
+              },
+            ],
+          },
+          agentId: "main",
+          senderIsOwner: true,
+          turnId: "turn-sibling-route",
+          conversationRef: conversation.conversationRef,
+          message: "hello",
+          timeoutMs: 1,
+        },
+        deps,
+      ),
+    ).rejects.toBeInstanceOf(ConversationInputError);
+    expect(deps.resolveOutboundChannelPlugin).not.toHaveBeenCalled();
+    expect(deps.beginOperation).not.toHaveBeenCalled();
+    expect(deps.runMessageAction).not.toHaveBeenCalled();
+  });
+
   it("creates a context binding only when a discovered address starts a turn", async () => {
     const deps = createDeps();
     const {
@@ -168,6 +202,11 @@ describe("runGatewayConversationTurn", () => {
       ...unbound
     } = conversation;
     deps.resolveConversation.mockReturnValueOnce(unbound).mockReturnValue(conversation);
+    deps.bindOutboundSessionEntry.mockImplementationOnce(
+      async (params: { assertCommitAllowed?: () => void }) => {
+        params.assertCommitAllowed?.();
+      },
+    );
     deps.runMessageAction = vi.fn(async (input: Record<string, unknown>) => {
       persistIntent(input);
       return sentResult();
@@ -197,6 +236,54 @@ describe("runGatewayConversationTurn", () => {
     );
   });
 
+  it("rejects a route-owner change at the outbound session binding commit", async () => {
+    const deps = createDeps();
+    const {
+      sessionId: _sessionId,
+      sessionKey: _sessionKey,
+      role: _role,
+      ...unbound
+    } = conversation;
+    deps.resolveConversation.mockReturnValue(unbound);
+    deps.bindOutboundSessionEntry.mockImplementationOnce(
+      async (params: { assertCommitAllowed?: () => void }) => {
+        params.assertCommitAllowed?.();
+      },
+    );
+    const readCurrentConfig = vi
+      .fn()
+      .mockReturnValueOnce({})
+      .mockReturnValue({
+        agents: { entries: { main: {}, finance: {} } },
+        bindings: [
+          {
+            type: "route",
+            agentId: "finance",
+            match: { channel: "reef", accountId: "default" },
+          },
+        ],
+      });
+
+    await expect(
+      runGatewayConversationTurn(
+        {
+          config: {},
+          readCurrentConfig,
+          agentId: "main",
+          senderIsOwner: true,
+          turnId: "turn-revoked-during-bind",
+          conversationRef: conversation.conversationRef,
+          message: "hello molty",
+          timeoutMs: 1,
+        },
+        deps,
+      ),
+    ).rejects.toBeInstanceOf(PlatformMessageNotDispatchedError);
+
+    expect(deps.beginOperation).not.toHaveBeenCalled();
+    expect(deps.runMessageAction).not.toHaveBeenCalled();
+  });
+
   it("registers correlation before durable delivery and consumes a fast reply inline", async () => {
     const deps = createDeps();
     let capture: Promise<void> | undefined;
@@ -319,8 +406,6 @@ describe("runGatewayConversationTurn", () => {
       createdAt: 100,
       updatedAt: 300,
     });
-    deps.resolveConversation.mockReturnValue(undefined);
-
     await expect(
       runGatewayConversationTurn(
         {
@@ -335,11 +420,57 @@ describe("runGatewayConversationTurn", () => {
         deps,
       ),
     ).resolves.toMatchObject({ status: "replied", reply: { text: "ack" } });
-    expect(deps.resolveConversation).not.toHaveBeenCalled();
+    expect(deps.resolveConversation).toHaveBeenCalled();
     expect(deps.runMessageAction).not.toHaveBeenCalled();
     expect(deps.resolveOutboundChannelPlugin).not.toHaveBeenCalled();
   });
 
+  it("does not reveal a completed reply after the route owner changes", async () => {
+    const deps = createDeps();
+    deps.operations.set("turn-reassigned", {
+      operationId: "turn-reassigned",
+      operationKind: "turn",
+      conversationRef: conversation.conversationRef,
+      channel: conversation.channel,
+      messageHash: "hello",
+      status: "replied",
+      preparedMessageId: "reef-outbound-1",
+      platformMessageId: "reef-outbound-1",
+      reply: {
+        messageId: "reply-private",
+        replyToId: "reef-outbound-1",
+        text: "private finance reply",
+        timestamp: 300,
+      },
+      createdAt: 100,
+      updatedAt: 300,
+    });
+
+    await expect(
+      runGatewayConversationTurn(
+        {
+          config: {
+            agents: { entries: { main: {}, finance: {} } },
+            bindings: [
+              {
+                type: "route",
+                agentId: "finance",
+                match: { channel: "reef", accountId: "default" },
+              },
+            ],
+          },
+          agentId: "main",
+          senderIsOwner: true,
+          turnId: "turn-reassigned",
+          conversationRef: conversation.conversationRef,
+          message: "hello",
+          timeoutMs: 1_000,
+        },
+        deps,
+      ),
+    ).rejects.toBeInstanceOf(ConversationInputError);
+  });
+
   it("returns queued state without retrying recipient-visible I/O", async () => {
     const deps = createDeps();
     deps.operations.set("turn-queued", {
@@ -512,6 +643,46 @@ describe("runGatewayConversationTurn", () => {
     });
   });
 
+  it("rejects delivery after the admitted session generation is replaced", async () => {
+    const deps = createDeps();
+    let current = conversation;
+    deps.resolveConversation.mockImplementation(() => current);
+    deps.runMessageAction = vi.fn(async (input: Record<string, unknown>) => {
+      persistIntent(input);
+      current = {
+        ...conversation,
+        sessionId: "replacement-session",
+        sessionKey: "agent:main:reef:direct:replacement",
+      };
+      try {
+        await (input.onDeliveryAttempt as () => Promise<void>)();
+      } catch (error) {
+        deps.update("turn-replaced-session", {
+          status: "rejected",
+          rejectionError: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+      }
+      return sentResult();
+    }) as never;
+
+    await expect(
+      runGatewayConversationTurn(
+        {
+          config: {},
+          agentId: "main",
+          senderIsOwner: true,
+          turnId: "turn-replaced-session",
+          conversationRef: conversation.conversationRef,
+          message: "hello",
+          timeoutMs: 1_000,
+        },
+        deps,
+      ),
+    ).rejects.toMatchObject({ name: "ConversationInputError" });
+    expect(deps.runMessageAction).toHaveBeenCalledOnce();
+  });
+
   it("rejects unsupported channels before registering or sending", async () => {
     const deps = createDeps();
     const {
diff --git a/src/gateway/conversation-turn.ts b/src/gateway/conversation-turn.ts
index 1f53581099d2..62d4686315a7 100644
--- a/src/gateway/conversation-turn.ts
+++ b/src/gateway/conversation-turn.ts
@@ -7,6 +7,7 @@ import {
   type ConversationRecord,
   type ConversationRegistryScope,
 } from "../config/sessions/conversation-registry.js";
+import { resolveConversationRouteFingerprint } from "../config/sessions/conversation-route-fingerprint.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveOutboundChannelPlugin } from "../infra/outbound/channel-resolution.js";
 import {
@@ -24,6 +25,10 @@ import {
   ConversationInputError,
   ConversationOperationConflictError,
 } from "./conversation-errors.js";
+import {
+  assertConversationDeliveryAttemptAuthorized,
+  assertConversationRouteEligibleForAgent,
+} from "./conversation-route-ownership.js";
 
 type ConversationTurnDeps = ConversationDeliveryDeps & {
   registerPendingConversationTurn: typeof registerPendingConversationTurn;
@@ -166,6 +171,8 @@ async function ensureConversationContextBinding(params: {
   agentId: string;
   conversation: ConversationRecord;
   plugin: ReturnType<typeof resolveOutboundChannelPlugin>;
+  expectedRouteFingerprint: string;
+  readCurrentConfig: () => OpenClawConfig;
 }): Promise<BoundConversationRecord> {
   if (hasConversationSessionBinding(params.conversation)) {
     return params.conversation;
@@ -190,6 +197,18 @@ async function ensureConversationContextBinding(params: {
     channel,
     accountId: params.conversation.accountId,
     route,
+    // Route resolution can await plugin work; replay authority at the exact
+    // session-binding commit so a concurrent config change cannot persist it.
+    assertCommitAllowed: () => {
+      assertConversationDeliveryAttemptAuthorized({
+        config: params.readCurrentConfig(),
+        agentId: params.agentId,
+        conversationRef: params.conversation.conversationRef,
+        expectedRouteFingerprint: params.expectedRouteFingerprint,
+        scope: params.scope,
+        resolveConversation: params.deps.resolveConversation,
+      });
+    },
   });
   const bound = params.deps.resolveConversation(params.scope, params.conversation.conversationRef);
   if (!bound || !hasConversationSessionBinding(bound)) {
@@ -204,6 +223,7 @@ async function ensureConversationContextBinding(params: {
 export async function runGatewayConversationTurn(
   params: {
     config: OpenClawConfig;
+    readCurrentConfig?: () => OpenClawConfig;
     agentId: string;
     senderIsOwner: boolean;
     sourceSessionKey?: string;
@@ -227,10 +247,6 @@ export async function runGatewayConversationTurn(
         message: params.message,
         ...(prior.preparedMessageId ? { preparedMessageId: prior.preparedMessageId } : {}),
       });
-      const completed = resultForCompletedOperation({ operation: begun.record });
-      if (completed) {
-        return completed;
-      }
     }
   } catch (error) {
     if (error instanceof ConversationDeliveryInputError) {
@@ -245,15 +261,29 @@ export async function runGatewayConversationTurn(
       `Conversation not found: ${params.conversationRef} (use conversations_list)`,
     );
   }
+  const readCurrentConfig = params.readCurrentConfig ?? (() => params.config);
+  const currentConfig = readCurrentConfig();
+  assertConversationRouteEligibleForAgent({
+    config: currentConfig,
+    agentId: params.agentId,
+    conversation: discoveredConversation,
+  });
+  const discoveredRouteFingerprint = resolveConversationRouteFingerprint(discoveredConversation);
+  if (begun) {
+    const completed = resultForCompletedOperation({ operation: begun.record });
+    if (completed) {
+      return completed;
+    }
+  }
   const plugin = deps.resolveOutboundChannelPlugin({
     channel: discoveredConversation.channel,
-    cfg: params.config,
+    cfg: currentConfig,
   });
   const candidatePreparedMessageId = begun
     ? begun.record.preparedMessageId
     : prepareConversationMessageId({
         plugin,
-        config: params.config,
+        config: currentConfig,
         conversation: discoveredConversation,
         message: params.message,
       });
@@ -265,11 +295,20 @@ export async function runGatewayConversationTurn(
   const conversation = await ensureConversationContextBinding({
     deps,
     scope,
-    config: params.config,
+    config: currentConfig,
     agentId: params.agentId,
     conversation: discoveredConversation,
     plugin,
+    expectedRouteFingerprint: discoveredRouteFingerprint,
+    readCurrentConfig,
   });
+  const authorizedConfig = readCurrentConfig();
+  assertConversationRouteEligibleForAgent({
+    config: authorizedConfig,
+    agentId: params.agentId,
+    conversation,
+  });
+  const routeFingerprint = resolveConversationRouteFingerprint(conversation);
   if (!begun) {
     try {
       begun = deps.beginOperation(scope, {
@@ -317,7 +356,7 @@ export async function runGatewayConversationTurn(
       context: {
         agentId: params.agentId,
         ...(params.sourceSessionKey ? { sourceSessionKey: params.sourceSessionKey } : {}),
-        config: params.config,
+        config: authorizedConfig,
         senderIsOwner: params.senderIsOwner,
       },
       conversation,
@@ -326,6 +365,19 @@ export async function runGatewayConversationTurn(
       operationKind: "turn",
       operation: begun.record,
       preparedMessageId,
+      routeFingerprint,
+      onDeliveryAttempt: async () => {
+        assertConversationDeliveryAttemptAuthorized({
+          config: readCurrentConfig(),
+          agentId: params.agentId,
+          conversationRef: conversation.conversationRef,
+          expectedRouteFingerprint: routeFingerprint,
+          expectedSessionId: conversation.sessionId,
+          expectedSessionKey: conversation.sessionKey,
+          scope,
+          resolveConversation: deps.resolveConversation,
+        });
+      },
     });
     if (sent.deliveryStatus !== "sent") {
       pending.cancel();
diff --git a/src/gateway/server-methods/conversations.ts b/src/gateway/server-methods/conversations.ts
index 3846576d5498..cefdd97bdcb0 100644
--- a/src/gateway/server-methods/conversations.ts
+++ b/src/gateway/server-methods/conversations.ts
@@ -245,11 +245,14 @@ export function createConversationHandlers(
         return;
       }
       const request = params as ConversationListParams;
+      const readCurrentConfig = () =>
+        resolveGatewayPluginConfig({ config: context.getRuntimeConfig() });
       try {
         respond(
           true,
           await deps.runConversationList({
-            config: resolveGatewayPluginConfig({ config: context.getRuntimeConfig() }),
+            config: readCurrentConfig(),
+            readCurrentConfig,
             agentId: request.agentId,
             ...(request.channel ? { channel: request.channel } : {}),
             ...(request.query ? { query: request.query } : {}),
@@ -275,7 +278,9 @@ export function createConversationHandlers(
         return;
       }
       const request = params as ConversationSendParams;
-      const config = resolveGatewayPluginConfig({ config: context.getRuntimeConfig() });
+      const readCurrentConfig = () =>
+        resolveGatewayPluginConfig({ config: context.getRuntimeConfig() });
+      const config = readCurrentConfig();
       if (
         !validateConversationSourceSession({
           config,
@@ -318,6 +323,7 @@ export function createConversationHandlers(
         execute: async () =>
           await deps.runConversationSend({
             config,
+            readCurrentConfig,
             agentId: request.agentId,
             senderIsOwner: isAuthenticatedOwner(client),
             ...(request.sourceSessionKey ? { sourceSessionKey: request.sourceSessionKey } : {}),
@@ -357,7 +363,9 @@ export function createConversationHandlers(
         return;
       }
       const request = params as ConversationTurnParams;
-      const config = resolveGatewayPluginConfig({ config: context.getRuntimeConfig() });
+      const readCurrentConfig = () =>
+        resolveGatewayPluginConfig({ config: context.getRuntimeConfig() });
+      const config = readCurrentConfig();
       if (
         !validateConversationSourceSession({
           config,
@@ -401,6 +409,7 @@ export function createConversationHandlers(
         execute: async () =>
           await deps.runConversationTurn({
             config,
+            readCurrentConfig,
             agentId: request.agentId,
             senderIsOwner: isAuthenticatedOwner(client),
             ...(request.sourceSessionKey ? { sourceSessionKey: request.sourceSessionKey } : {}),
diff --git a/src/gateway/server-runtime-services.test.ts b/src/gateway/server-runtime-services.test.ts
index 0decf206d5b5..b1ca12b13c5e 100644
--- a/src/gateway/server-runtime-services.test.ts
+++ b/src/gateway/server-runtime-services.test.ts
@@ -63,6 +63,7 @@ const hoisted = vi.hoisted(() => {
     deliverQueuedSessionDelivery: vi.fn(async () => undefined),
     settleQueuedSessionDelivery: vi.fn(async () => undefined),
     deliverOutboundPayloads: vi.fn(),
+    assertQueuedConversationDeliveryAttemptAuthorized: vi.fn(),
   };
 });
 
@@ -92,6 +93,11 @@ vi.mock("../infra/outbound/delivery-queue-migration.js", () => ({
   migrateLegacyPendingOutboundDeliveries: hoisted.migrateLegacyPendingOutboundDeliveries,
 }));
 
+vi.mock("./conversation-route-ownership.js", () => ({
+  assertQueuedConversationDeliveryAttemptAuthorized:
+    hoisted.assertQueuedConversationDeliveryAttemptAuthorized,
+}));
+
 vi.mock("../infra/session-delivery-queue-runtime.js", () => ({
   startSessionDeliveryRuntime: hoisted.startSessionDeliveryRuntime,
   schedulePendingSessionDeliveries: hoisted.schedulePendingSessionDeliveries,
@@ -159,6 +165,7 @@ describe("server-runtime-services", () => {
     hoisted.deliverQueuedSessionDelivery.mockClear();
     hoisted.settleQueuedSessionDelivery.mockClear();
     hoisted.deliverOutboundPayloads.mockClear();
+    hoisted.assertQueuedConversationDeliveryAttemptAuthorized.mockReset();
   });
 
   afterEach(() => {
@@ -380,7 +387,7 @@ describe("server-runtime-services", () => {
       throw new Error("Expected delivery recovery log children");
     }
     expect(hoisted.recoverPendingDeliveries).toHaveBeenCalledWith({
-      deliver: hoisted.deliverOutboundPayloads,
+      deliver: expect.any(Function),
       cfg: {},
       log: deliveryLog,
     });
@@ -664,7 +671,7 @@ describe("server-runtime-services", () => {
     const [drain] = hoisted.drainPendingDeliveries.mock.calls[0] ?? [];
     expect(drain).toMatchObject({
       drainKey: "gateway:outbound",
-      deliver: hoisted.deliverOutboundPayloads,
+      deliver: expect.any(Function),
     });
     expect(drain?.selectEntry({ channel: "discord" } as never, Date.now())).toEqual({
       match: true,
@@ -673,6 +680,49 @@ describe("server-runtime-services", () => {
     services.heartbeatRunner.stop();
   });
 
+  it("reconstructs conversation route authorization for a recovered delivery attempt", async () => {
+    vi.useFakeTimers();
+    const { services } = activateScheduledServicesForTest({ startCron: false });
+    await vi.dynamicImportSettled();
+    const recovery = hoisted.recoverPendingDeliveries.mock.calls[0]?.[0];
+    if (!recovery) {
+      throw new Error("Expected outbound recovery to start");
+    }
+    hoisted.deliverOutboundPayloads.mockImplementationOnce(async (params) => {
+      await params.onDeliveryAttempt?.();
+      return [];
+    });
+    const denial = new Error("conversation route reassigned");
+    hoisted.assertQueuedConversationDeliveryAttemptAuthorized.mockImplementationOnce(() => {
+      throw denial;
+    });
+
+    await expect(
+      recovery.deliver({
+        cfg: {},
+        channel: "reef",
+        to: "reef:molty",
+        payloads: [{ text: "hello" }],
+        conversationDeliveryAttemptAuthority: {
+          agentId: "main",
+          operationId: "operation-recovery",
+          storePath: "/tmp/agent.sqlite",
+          routeFingerprint: "route-recovery",
+        },
+      }),
+    ).rejects.toBe(denial);
+
+    expect(hoisted.assertQueuedConversationDeliveryAttemptAuthorized).toHaveBeenCalledWith(
+      expect.objectContaining({
+        agentId: "main",
+        operationId: "operation-recovery",
+        storePath: "/tmp/agent.sqlite",
+        routeFingerprint: "route-recovery",
+      }),
+    );
+    services.heartbeatRunner.stop();
+  });
+
   it("uses the current runtime config when retrying queued outbound deliveries", async () => {
     vi.useFakeTimers();
     const configModule = await import("../config/config.js");
diff --git a/src/gateway/server-runtime-services.ts b/src/gateway/server-runtime-services.ts
index fccc68e65955..a3e1c74491d8 100644
--- a/src/gateway/server-runtime-services.ts
+++ b/src/gateway/server-runtime-services.ts
@@ -10,6 +10,7 @@ import {
   runHeartbeatOnce,
 } from "../infra/heartbeat-runner.js";
 import { resolveHeartbeatIntervalMs } from "../infra/heartbeat-summary.js";
+import type { DeliverOutboundPayloadsParams } from "../infra/outbound/deliver.js";
 import {
   schedulePendingSessionDeliveries,
   startSessionDeliveryRuntime,
@@ -19,6 +20,8 @@ import {
   runWithGatewayIndependentRootWorkAdmission,
 } from "../process/gateway-work-admission.js";
 import { startSessionUpstreamMonitor } from "../sessions/session-upstream-monitor.js";
+import { assertQueuedConversationDeliveryAttemptAuthorized } from "./conversation-route-ownership.js";
+import { resolveGatewayPluginConfig } from "./runtime-plugin-config.js";
 import {
   fenceScheduledGatewayContextResolver,
   runWithScheduledGatewayContext,
@@ -215,6 +218,34 @@ function startPendingOutboundDeliveryRecovery(params: {
       if (stopped) {
         return;
       }
+      const deliverWithCurrentConversationAuthority = async (
+        deliveryParams: DeliverOutboundPayloadsParams,
+      ) => {
+        const completion = deliveryParams.deliveryCompletion;
+        const attemptAuthority =
+          completion?.kind === "conversation"
+            ? completion
+            : deliveryParams.conversationDeliveryAttemptAuthority;
+        if (!attemptAuthority) {
+          return await deliverOutboundPayloadsInternal(deliveryParams);
+        }
+        return await deliverOutboundPayloadsInternal({
+          ...deliveryParams,
+          onDeliveryAttempt: async () => {
+            await deliveryParams.onDeliveryAttempt?.();
+            if (!attemptAuthority.routeFingerprint) {
+              return;
+            }
+            assertQueuedConversationDeliveryAttemptAuthorized({
+              config: resolveGatewayPluginConfig({ config: getRuntimeConfig() }),
+              agentId: attemptAuthority.agentId,
+              operationId: attemptAuthority.operationId,
+              ...(attemptAuthority.storePath ? { storePath: attemptAuthority.storePath } : {}),
+              routeFingerprint: attemptAuthority.routeFingerprint,
+            });
+          },
+        });
+      };
       logRecovery ??= params.log.child("delivery-recovery");
       if (migrationPending) {
         const cfg = initialPass ? params.cfg : getRuntimeConfig();
@@ -229,7 +260,7 @@ function startPendingOutboundDeliveryRecovery(params: {
         // one pass neither skipped ownership nor left retired rows behind.
         migrationPending = migration.skipped > 0 || migration.remaining > 0;
         await recoverPendingDeliveries({
-          deliver: deliverOutboundPayloadsInternal,
+          deliver: deliverWithCurrentConversationAuthority,
           log: logRecovery,
           cfg,
         });
@@ -242,7 +273,7 @@ function startPendingOutboundDeliveryRecovery(params: {
         logLabel: "Outbound delivery retry",
         cfg: getRuntimeConfig(),
         log: logRecovery,
-        deliver: deliverOutboundPayloadsInternal,
+        deliver: deliverWithCurrentConversationAuthority,
         selectEntry: () => ({ match: true, bypassBackoff: false }),
       });
     }).catch((err: unknown) => params.log.error(`Delivery recovery failed: ${String(err)}`));
diff --git a/src/infra/outbound/conversation-delivery.ts b/src/infra/outbound/conversation-delivery.ts
index 3150ece20fc3..80ee6c792ad2 100644
--- a/src/infra/outbound/conversation-delivery.ts
+++ b/src/infra/outbound/conversation-delivery.ts
@@ -147,6 +147,8 @@ export async function sendGatewayConversationMessage(params: {
   operationKind: ConversationDeliveryRecord["operationKind"];
   operation?: ConversationDeliveryRecord;
   preparedMessageId?: string;
+  routeFingerprint: string;
+  onDeliveryAttempt: () => Promise<void>;
   signal?: AbortSignal;
 }): Promise<ConversationMessageDeliveryResult> {
   const scope = resolveConversationDeliveryStoreScope(params.context);
@@ -203,8 +205,10 @@ export async function sendGatewayConversationMessage(params: {
         agentId: scope.agentId,
         operationId: begun.record.operationId,
         ...(scope.storePath ? { storePath: scope.storePath } : {}),
+        routeFingerprint: params.routeFingerprint,
       },
       onDeliveryIntent,
+      onDeliveryAttempt: params.onDeliveryAttempt,
       ...(begun.record.preparedMessageId
         ? { preparedMessageId: begun.record.preparedMessageId }
         : {}),
diff --git a/src/infra/outbound/current-conversation-bindings.ts b/src/infra/outbound/current-conversation-bindings.ts
index c1130160dd15..c7a3331c63fd 100644
--- a/src/infra/outbound/current-conversation-bindings.ts
+++ b/src/infra/outbound/current-conversation-bindings.ts
@@ -321,15 +321,12 @@ export function deleteCurrentConversationBindingRecordsBySession(
   });
 }
 
-function resolveChannelSupportsCurrentConversationBinding(params: {
-  channel: string;
-  accountId: string;
-}): boolean {
+function resolveChannelConversationBindingSupport(params: { channel: string; accountId: string }) {
   const normalized =
     normalizeAnyChannelId(params.channel) ??
     normalizeOptionalLowercaseString(normalizeConversationText(params.channel));
   if (!normalized) {
-    return false;
+    return undefined;
   }
   const matchesPluginId = (plugin: {
     id?: string | null;
@@ -345,8 +342,19 @@ function resolveChannelSupportsCurrentConversationBinding(params: {
   const plugin = (getActivePluginChannelRegistryFromState()?.channels ?? []).find((entry) =>
     matchesPluginId(entry.plugin),
   )?.plugin;
-  const bindingSupport = plugin?.conversationBindings;
-  if (bindingSupport?.supportsCurrentConversationBinding !== true) {
+  return plugin?.conversationBindings;
+}
+
+function resolveChannelSupportsCurrentConversationBinding(params: {
+  channel: string;
+  accountId: string;
+}): boolean {
+  const bindingSupport = resolveChannelConversationBindingSupport(params);
+  if (
+    bindingSupport?.supportsCurrentConversationBinding !== true ||
+    bindingSupport.bindingStore === "adapter" ||
+    typeof bindingSupport.createManager === "function"
+  ) {
     return false;
   }
   return (
@@ -354,6 +362,15 @@ function resolveChannelSupportsCurrentConversationBinding(params: {
   );
 }
 
+/** True when an active channel lifecycle owns bindings through a registered adapter. */
+export function requiresRegisteredSessionBindingAdapter(params: {
+  channel: string;
+  accountId: string;
+}): boolean {
+  const support = resolveChannelConversationBindingSupport(params);
+  return support?.bindingStore === "adapter" || typeof support?.createManager === "function";
+}
+
 function supportsGenericCurrentConversationBinding(ref: {
   channel: string;
   accountId: string;
diff --git a/src/infra/outbound/deliver-contracts.ts b/src/infra/outbound/deliver-contracts.ts
index 8e335e1ce05b..d0b292322cb2 100644
--- a/src/infra/outbound/deliver-contracts.ts
+++ b/src/infra/outbound/deliver-contracts.ts
@@ -28,6 +28,11 @@ import type { PreparedOutboundBatch } from "./prepared-batch.js";
 import type { OutboundSendDeps } from "./send-deps.js";
 import type { OutboundSessionContext } from "./session-context.js";
 
+type ConversationDeliveryAttemptAuthority = Omit<
+  Extract<DurableDeliveryCompletion, { kind: "conversation" }>,
+  "kind"
+>;
+
 export type OutboundDeliveryQueuePolicy = "required" | "best_effort";
 
 export type OutboundDeliveryIntent = {
@@ -196,6 +201,10 @@ export type DeliverOutboundPayloadsCoreParams = {
   reusePendingDeliveryIntent?: boolean;
   /** @internal Serializable owner state finalized after live or recovered delivery. */
   deliveryCompletion?: DurableDeliveryCompletion;
+  /** @internal Ephemeral route authority for a recovered attempt; never owns completion. */
+  conversationDeliveryAttemptAuthority?: ConversationDeliveryAttemptAuthority;
+  /** @internal Revalidates authority once per durable queue execution, before adapter fanout. */
+  onDeliveryAttempt?: () => Promise<void>;
   /** @internal Channel-valid id reserved before a correlated conversation turn is sent. */
   preparedMessageId?: string;
   /** @internal Recheck the concrete post-hook send shape before platform I/O. */
diff --git a/src/infra/outbound/deliver-queue-execute.ts b/src/infra/outbound/deliver-queue-execute.ts
index ef650e64c343..84ff49a347ab 100644
--- a/src/infra/outbound/deliver-queue-execute.ts
+++ b/src/infra/outbound/deliver-queue-execute.ts
@@ -20,6 +20,7 @@ import {
 } from "./deliver-queue-state.js";
 import {
   OutboundDeliveryError,
+  PlatformMessageNotDispatchedError,
   type OutboundDeliveryResult,
   type OutboundPayloadDeliveryOutcome,
 } from "./deliver-types.js";
@@ -307,6 +308,24 @@ export async function deliverOutboundPayloadsWithQueueCleanup(
 
   try {
     throwIfProducerLeaseLost();
+    const conversationAttemptAuthority =
+      params.deliveryCompletion?.kind === "conversation"
+        ? params.deliveryCompletion
+        : params.conversationDeliveryAttemptAuthority;
+    if (conversationAttemptAuthority) {
+      // Conversation delivery was not stable-shipped before route fingerprints. An unfinished
+      // legacy intent cannot be rebound safely after upgrade, so missing authority fails closed.
+      if (!conversationAttemptAuthority.routeFingerprint || !params.onDeliveryAttempt) {
+        throw new PlatformMessageNotDispatchedError(
+          "Conversation delivery is missing its current route authorization",
+          { cause: undefined, retryable: false },
+        );
+      }
+      // One durable attempt admits its bounded adapter fanout/retries. A later queue or recovery
+      // attempt rechecks from the serialized fingerprint; in-flight revocation is not promised.
+      await params.onDeliveryAttempt();
+      throwIfProducerLeaseLost();
+    }
     const results = await deliverOutboundPayloadsCore(wrappedParams);
     // Core reconciles adapter progress objects with hook-bearing final results.
     deliveredResults = results;
diff --git a/src/infra/outbound/deliver.test.ts b/src/infra/outbound/deliver.test.ts
index 374baee69921..9ced43989c15 100644
--- a/src/infra/outbound/deliver.test.ts
+++ b/src/infra/outbound/deliver.test.ts
@@ -880,7 +880,9 @@ describe("deliverOutboundPayloads", () => {
         kind: "conversation",
         agentId: "main",
         operationId: "operation-1",
+        routeFingerprint: "route-1",
       },
+      onDeliveryAttempt: async () => {},
     });
 
     expect(order).toEqual([
@@ -968,6 +970,33 @@ describe("deliverOutboundPayloads", () => {
     expect(messageSendText).not.toHaveBeenCalled();
   });
 
+  it("fails closed for an unfinished conversation intent without route authority", async () => {
+    const messageSendText = vi.fn(async () => ({
+      messageId: "should-not-send",
+      receipt: createMessageReceiptFromOutboundResults({
+        results: [{ channel: "matrix", messageId: "should-not-send" }],
+        kind: "text",
+      }),
+    }));
+    setMatrixMessageAdapter({
+      id: "matrix",
+      durableFinal: { capabilities: { text: true } },
+      send: { text: messageSendText },
+    });
+
+    await expect(
+      deliverMatrix({
+        deliveryCompletion: {
+          kind: "conversation",
+          agentId: "main",
+          operationId: "legacy-operation",
+        },
+        onDeliveryAttempt: async () => {},
+      }),
+    ).rejects.toMatchObject({ retryable: false });
+    expect(messageSendText).not.toHaveBeenCalled();
+  });
+
   it("does not claim platform custody when message adapter preflight fails", async () => {
     const messageSendText = vi.fn();
     setMatrixMessageAdapter({
@@ -1096,11 +1125,48 @@ describe("deliverOutboundPayloads", () => {
     expect(hookMocks.runner.runMessageSending).not.toHaveBeenCalled();
   });
 
+  it("revalidates conversation authority after queue admission and before the adapter", async () => {
+    const order: string[] = [];
+    queueMocks.enqueueDelivery.mockImplementationOnce(async () => {
+      order.push("queue");
+      return "queue-route-authorization";
+    });
+    const sendMatrix = vi.fn(async () => {
+      order.push("send");
+      return { messageId: "message-1" };
+    });
+
+    await expect(
+      deliverMatrix({
+        payloads: [{ text: "hello" }],
+        deps: { matrix: sendMatrix },
+        queuePolicy: "required",
+        deliveryCompletion: {
+          kind: "conversation",
+          agentId: "main",
+          operationId: "operation-revoked",
+          routeFingerprint: "route-revoked",
+        },
+        onDeliveryAttempt: async () => {
+          order.push("authorize");
+          throw new PlatformMessageNotDispatchedError("route was revoked", {
+            cause: undefined,
+            retryable: false,
+          });
+        },
+      }),
+    ).rejects.toThrow("route was revoked");
+
+    expect(order).toEqual(["queue", "authorize"]);
+    expect(sendMatrix).not.toHaveBeenCalled();
+  });
+
   it("finalizes owner state only after a chunked batch completes", async () => {
     const sendMatrix = vi
       .fn()
       .mockResolvedValueOnce({ messageId: "chunk-1" })
       .mockResolvedValueOnce({ messageId: "chunk-2" });
+    const onDeliveryAttempt = vi.fn(async () => {});
 
     await deliverMatrix({
       cfg: { channels: { matrix: { textChunkLimit: 2 } } } as OpenClawConfig,
@@ -1111,9 +1177,12 @@ describe("deliverOutboundPayloads", () => {
         kind: "conversation",
         agentId: "main",
         operationId: "operation-chunked",
+        routeFingerprint: "route-chunked",
       },
+      onDeliveryAttempt,
     });
 
+    expect(onDeliveryAttempt).toHaveBeenCalledOnce();
     expect(sendMatrix).toHaveBeenCalledTimes(2);
     expect(completionMocks.completeDurableDelivery).toHaveBeenCalledOnce();
     expect(completionMocks.completeDurableDelivery).toHaveBeenCalledWith(
@@ -1158,7 +1227,9 @@ describe("deliverOutboundPayloads", () => {
         kind: "conversation",
         agentId: "main",
         operationId: "operation-suppressed",
+        routeFingerprint: "route-suppressed",
       },
+      onDeliveryAttempt: async () => {},
     });
 
     expect(results).toEqual([]);
@@ -1634,7 +1705,9 @@ describe("deliverOutboundPayloads", () => {
           kind: "conversation",
           agentId: "main",
           operationId: "suppressed-metadata",
+          routeFingerprint: "route-suppressed-metadata",
         },
+        onDeliveryAttempt: async () => {},
         onPayloadDeliveryOutcome: (outcome) => outcomes.push(outcome),
       }),
     ).resolves.toEqual([]);
@@ -2254,7 +2327,9 @@ describe("deliverOutboundPayloads", () => {
           kind: "conversation",
           agentId: "main",
           operationId: "operation-rejected",
+          routeFingerprint: "route-rejected",
         },
+        onDeliveryAttempt: async () => {},
       }),
     ).rejects.toThrow("atomic message limit");
 
@@ -2293,7 +2368,9 @@ describe("deliverOutboundPayloads", () => {
           kind: "conversation",
           agentId: "main",
           operationId: "operation-empty-rejection",
+          routeFingerprint: "route-empty-rejection",
         },
+        onDeliveryAttempt: async () => {},
       }),
     ).rejects.toThrow("Platform rejected the message before dispatch");
 
diff --git a/src/infra/outbound/delivery-completion.ts b/src/infra/outbound/delivery-completion.ts
index 9e3a4303b810..8bac329e2841 100644
--- a/src/infra/outbound/delivery-completion.ts
+++ b/src/infra/outbound/delivery-completion.ts
@@ -18,6 +18,8 @@ export type DurableDeliveryCompletion =
       agentId: string;
       operationId: string;
       storePath?: string;
+      /** Present on Gateway-owned conversation intents created with route authorization. */
+      routeFingerprint?: string;
     }
   | {
       kind: "pending-final";
diff --git a/src/infra/outbound/delivery-queue-recovery.ts b/src/infra/outbound/delivery-queue-recovery.ts
index 928dbdcb2b1c..f96481f1683c 100644
--- a/src/infra/outbound/delivery-queue-recovery.ts
+++ b/src/infra/outbound/delivery-queue-recovery.ts
@@ -284,6 +284,8 @@ function buildRecoveryDeliverParams(
   stateDir?: string,
   producerClaimId?: string,
 ) {
+  const conversationCompletion =
+    entry.deliveryCompletion?.kind === "conversation" ? entry.deliveryCompletion : undefined;
   return {
     cfg,
     channel: entry.channel,
@@ -310,6 +312,20 @@ function buildRecoveryDeliverParams(
     preparedMessageId: entry.preparedMessageId,
     // Recovery owns terminal completion because nested delivery only reports
     // process-local evidence that cannot survive another restart.
+    ...(conversationCompletion
+      ? {
+          conversationDeliveryAttemptAuthority: {
+            agentId: conversationCompletion.agentId,
+            operationId: conversationCompletion.operationId,
+            ...(conversationCompletion.storePath
+              ? { storePath: conversationCompletion.storePath }
+              : {}),
+            ...(conversationCompletion.routeFingerprint
+              ? { routeFingerprint: conversationCompletion.routeFingerprint }
+              : {}),
+          },
+        }
+      : {}),
     deliveryQueueId: entry.id,
     deliveryQueueStateDir: stateDir,
     ...(producerClaimId ? { deliveryProducerClaimId: producerClaimId } : {}),
diff --git a/src/infra/outbound/delivery-queue.reconnect-drain.test.ts b/src/infra/outbound/delivery-queue.reconnect-drain.test.ts
index 397006da137c..3a90bc98d7ae 100644
--- a/src/infra/outbound/delivery-queue.reconnect-drain.test.ts
+++ b/src/infra/outbound/delivery-queue.reconnect-drain.test.ts
@@ -1,10 +1,17 @@
 // Covers reconnect-triggered queue drain selection, active claims, backoff
 // bypass, and concurrent drain suppression.
+import path from "node:path";
 import { createRequireRecord } from "openclaw/plugin-sdk/test-fixtures";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { controlNextRecoverySleep } from "../../../test/helpers/infra/delivery-recovery.js";
 import type { OpenClawConfig } from "../../config/config.js";
+import { beginConversationDeliveryOperation } from "../../config/sessions/conversation-delivery-store.js";
+import { upsertSessionEntryCore } from "../../config/sessions/session-accessor.js";
+import { drainPendingDeliveries as drainPluginPendingDeliveries } from "../../plugin-sdk/delivery-queue-runtime.js";
+import { buildConversationRef } from "../../routing/conversation-ref.js";
 import { openOpenClawStateDatabase } from "../../state/openclaw-state-db.js";
+import { normalizeSessionDeliveryState } from "../../utils/delivery-context.shared.js";
+import { PlatformMessageNotDispatchedError } from "./deliver-types.js";
 import { OUTBOUND_DELIVERY_QUEUE_NAME } from "./delivery-queue-media-staging.js";
 import {
   type DeliverFn,
@@ -195,6 +202,80 @@ describe("drainPendingDeliveriesCore for reconnect", () => {
     expect(delivery.skipQueue).toBe(true);
   });
 
+  it("leaves Gateway conversation records for the authorized recovery owner", async () => {
+    const operationId = "conversation-reconnect";
+    const storePath = path.join(tmpDir, "agent-sessions.json");
+    const scope = { agentId: "main", storePath };
+    const conversationRef = buildConversationRef({
+      channel: "reef",
+      accountId: "default",
+      kind: "direct",
+      peerId: "peer-agent",
+    });
+    await upsertSessionEntryCore(
+      { ...scope, sessionKey: "agent:main:reef:direct:peer-agent" },
+      {
+        sessionId: "reef-session",
+        updatedAt: 100,
+        chatType: "direct",
+        delivery: normalizeSessionDeliveryState({
+          context: { channel: "reef", accountId: "default", to: "reef:peer-agent" },
+          origin: {
+            provider: "reef",
+            accountId: "default",
+            nativeDirectUserId: "peer-agent",
+          },
+        }),
+      },
+    );
+    beginConversationDeliveryOperation(scope, {
+      operationId,
+      operationKind: "send",
+      conversationRef,
+      message: "deliver only through the authorized recovery owner",
+      preparedMessageId: "reef-prepared",
+    });
+    const id = await enqueueDelivery(
+      {
+        channel: "reef",
+        to: "reef:peer-agent",
+        accountId: "default",
+        payloads: [{ text: "deliver only through the authorized recovery owner" }],
+        deliveryCompletion: {
+          kind: "conversation",
+          agentId: "main",
+          operationId,
+          storePath,
+          routeFingerprint: "route-reconnect",
+        },
+      },
+      tmpDir,
+    );
+    await failDelivery(id, NO_LISTENER_ERROR, tmpDir);
+    const deliver = vi.fn<DeliverFn>(async () => {
+      throw new PlatformMessageNotDispatchedError(
+        "Conversation delivery is missing its current route authorization",
+        { cause: undefined, retryable: false },
+      );
+    });
+
+    await drainPluginPendingDeliveries({
+      drainKey: "reef:default",
+      logLabel: "Reef reconnect drain",
+      cfg: stubCfg,
+      log: createRecoveryLog(),
+      stateDir: tmpDir,
+      deliver,
+      selectEntry: (entry) => ({
+        match: entry.channel === "reef" && entry.accountId === "default",
+        bypassBackoff: true,
+      }),
+    });
+
+    expect(deliver).not.toHaveBeenCalled();
+    expect((await loadPendingDeliveries(tmpDir)).map((entry) => entry.id)).toContain(id);
+  });
+
   it("skips entries from other accounts", async () => {
     const log = createRecoveryLog();
     const deliver = vi.fn<DeliverFn>(async () => {});
diff --git a/src/infra/outbound/delivery-queue.recovery.test.ts b/src/infra/outbound/delivery-queue.recovery.test.ts
index f1fa2518a279..ac67e3c95f61 100644
--- a/src/infra/outbound/delivery-queue.recovery.test.ts
+++ b/src/infra/outbound/delivery-queue.recovery.test.ts
@@ -351,6 +351,7 @@ describe("delivery-queue recovery", () => {
           agentId: "main",
           operationId,
           storePath,
+          routeFingerprint: "route-recovery",
         },
       },
       operationId,
@@ -421,7 +422,14 @@ describe("delivery-queue recovery", () => {
   it("finalizes a persisted conversation operation during queue recovery", async () => {
     const scope = await createConversationRecoveryFixture("operation-recovery");
     const deliveryResult = { channel: "reef" as const, messageId: "reef-platform" };
-    const deliver = vi.fn(async (params: { onDeliveryResult?: (result: unknown) => unknown }) => {
+    const deliver = vi.fn(async (params: Parameters<DeliverFn>[0]) => {
+      expect(params.deliveryCompletion).toBeUndefined();
+      expect(params.conversationDeliveryAttemptAuthority).toEqual({
+        agentId: "main",
+        operationId: "operation-recovery",
+        storePath: scope.storePath,
+        routeFingerprint: "route-recovery",
+      });
       await params.onDeliveryResult?.(deliveryResult);
       return [deliveryResult];
     });
diff --git a/src/infra/outbound/message-action-contracts.ts b/src/infra/outbound/message-action-contracts.ts
index 0687c6e5169d..9b487d551f95 100644
--- a/src/infra/outbound/message-action-contracts.ts
+++ b/src/infra/outbound/message-action-contracts.ts
@@ -94,6 +94,8 @@ export type MessageActionInput = {
   deliveryCompletion?: DurableDeliveryCompletion;
   /** @internal Runs after queue persistence and before platform I/O. */
   onDeliveryIntent?: (intent: DurableMessageSendIntent) => void;
+  /** @internal Revalidates caller-owned authority before each durable adapter attempt. */
+  onDeliveryAttempt?: () => Promise<void>;
   /** @internal Runs on identified platform evidence before queue acknowledgement. */
   onDeliveryResult?: (result: OutboundDeliveryResult) => Promise<void> | void;
   /** @internal Revalidates caller authority immediately before recipient-visible I/O. */
diff --git a/src/infra/outbound/message-action-send.ts b/src/infra/outbound/message-action-send.ts
index 5579b75e92c1..18e152b06e98 100644
--- a/src/infra/outbound/message-action-send.ts
+++ b/src/infra/outbound/message-action-send.ts
@@ -601,6 +601,7 @@ export async function executeMessageSend(ctx: ResolvedActionContext): Promise<Me
       onDeliveryIntent: input.onDeliveryIntent,
       onPlatformSendDispatch: input.onPlatformSendDispatch,
       skipQueue: input.skipQueue,
+      onDeliveryAttempt: input.onDeliveryAttempt,
       // Identified platform evidence is the first success proof on the core
       // path; commit the route here so the transcript mirror (which runs later
       // in the same delivery) can resolve a just-created session entry.
diff --git a/src/infra/outbound/message.ts b/src/infra/outbound/message.ts
index ffccd49002ab..1542d8577ad8 100644
--- a/src/infra/outbound/message.ts
+++ b/src/infra/outbound/message.ts
@@ -120,6 +120,8 @@ type MessageSendParams = {
   requireUnknownSendReconciliation?: boolean;
   /** @internal Runs after queue persistence and before platform I/O. */
   onDeliveryIntent?: (intent: DurableMessageSendIntent) => void;
+  /** @internal Revalidates authority once per durable queue execution, before adapter fanout. */
+  onDeliveryAttempt?: () => Promise<void>;
   /** @internal Runs on identified platform evidence before queue acknowledgement. */
   onDeliveryResult?: (result: OutboundDeliveryResult) => Promise<void> | void;
   /** @internal Revalidates caller authority immediately before recipient-visible I/O. */
@@ -455,6 +457,7 @@ export async function sendMessage(params: MessageSendParams): Promise<MessageSen
       reusePendingDeliveryIntent: params.reusePendingDeliveryIntent,
       completionRetention: params.completionRetention,
       ...(params.onDeliveryIntent ? { onDeliveryIntent: params.onDeliveryIntent } : {}),
+      ...(params.onDeliveryAttempt ? { onDeliveryAttempt: params.onDeliveryAttempt } : {}),
       ...(params.onDeliveryResult ? { onDeliveryResult: params.onDeliveryResult } : {}),
       ...(params.onPlatformSendDispatch
         ? { onPlatformSendDispatch: params.onPlatformSendDispatch }
diff --git a/src/infra/outbound/outbound-send-service.ts b/src/infra/outbound/outbound-send-service.ts
index b6ba17c918ed..3b3cf391ebb5 100644
--- a/src/infra/outbound/outbound-send-service.ts
+++ b/src/infra/outbound/outbound-send-service.ts
@@ -86,6 +86,8 @@ type OutboundSendContext = {
   deliveryCompletion?: DurableDeliveryCompletion;
   /** Runs after queue persistence and before platform I/O. */
   onDeliveryIntent?: (intent: DurableMessageSendIntent) => void;
+  /** Revalidates authority once per durable queue execution, before adapter fanout. */
+  onDeliveryAttempt?: () => Promise<void>;
   /** Runs on identified platform evidence before queue acknowledgement. */
   onDeliveryResult?: (result: OutboundDeliveryResult) => Promise<void> | void;
   /** Revalidates caller authority immediately before recipient-visible I/O. */
@@ -188,6 +190,7 @@ async function sendCoreMessage(params: {
     deliveryCompletion: params.ctx.deliveryCompletion,
     requireUnknownSendReconciliation: params.ctx.requireQueuePersistence ? false : undefined,
     onDeliveryIntent: params.ctx.onDeliveryIntent,
+    onDeliveryAttempt: params.ctx.onDeliveryAttempt,
     onDeliveryResult: params.ctx.onDeliveryResult,
     onPlatformSendDispatch: params.ctx.onPlatformSendDispatch,
     skipQueue: params.ctx.skipQueue,
diff --git a/src/infra/outbound/outbound-session.ts b/src/infra/outbound/outbound-session.ts
index 7e57cc8f40b5..f21713a00707 100644
--- a/src/infra/outbound/outbound-session.ts
+++ b/src/infra/outbound/outbound-session.ts
@@ -250,6 +250,8 @@ type OutboundSessionEntryParams = {
   channel: ChannelId;
   accountId?: string | null;
   route: OutboundSessionRoute;
+  /** Revalidates caller-owned route authority at the final persistence boundary. */
+  assertCommitAllowed?: () => void;
 };
 
 async function persistOutboundSessionEntry(
@@ -285,6 +287,7 @@ async function persistOutboundSessionEntry(
     accountId: params.accountId ?? undefined,
     threadId: params.route.threadId,
     ctx,
+    ...(params.assertCommitAllowed ? { assertCommitAllowed: params.assertCommitAllowed } : {}),
   });
 }
 
diff --git a/src/infra/outbound/session-binding-service.test.ts b/src/infra/outbound/session-binding-service.test.ts
index 1f5abb138161..033eaf9e675a 100644
--- a/src/infra/outbound/session-binding-service.test.ts
+++ b/src/infra/outbound/session-binding-service.test.ts
@@ -9,12 +9,14 @@ import { createTrackedTempDirs } from "../../test-utils/tracked-temp-dirs.js";
 import {
   testing,
   getSessionBindingService,
+  inspectSessionBindingByConversation,
   isSessionBindingError,
   registerSessionBindingAdapter,
   unregisterSessionBindingAdapter,
   type SessionBindingAdapter,
   type SessionBindingBindInput,
   type SessionBindingRecord,
+  type SessionBindingService,
 } from "./session-binding-service.js";
 
 type SessionBindingServiceModule = typeof import("./session-binding-service.js");
@@ -48,10 +50,60 @@ function setMinimalCurrentConversationRegistry(): void {
           },
         },
       },
+      {
+        pluginId: "adapter-chat",
+        source: "test",
+        plugin: {
+          id: "adapter-chat",
+          meta: { aliases: [] },
+          conversationBindings: {
+            supportsCurrentConversationBinding: true,
+            bindingStore: "adapter",
+          },
+        },
+      },
+      {
+        pluginId: "legacy-adapter-chat",
+        source: "test",
+        plugin: {
+          id: "legacy-adapter-chat",
+          meta: { aliases: [] },
+          conversationBindings: {
+            supportsCurrentConversationBinding: true,
+            createManager: () => ({ stop: () => undefined }),
+          },
+        },
+      },
     ]),
   );
 }
 
+it("keeps the stable session-binding service shape structurally assignable", () => {
+  const service: SessionBindingService = {
+    bind: async () => {
+      throw new Error("not implemented");
+    },
+    getCapabilities: () => ({
+      adapterAvailable: false,
+      bindSupported: false,
+      unbindSupported: false,
+      placements: [],
+    }),
+    listBySession: () => [],
+    resolveByConversation: () => null,
+    touch: () => {},
+    unbind: async () => [],
+  };
+
+  expect(
+    service.resolveByConversation({
+      channel: "demo",
+      accountId: "default",
+      conversationId: "room-1",
+    }),
+  ).toBeNull();
+});
+
 async function importSessionBindingServiceModule(
   cacheBust: string,
 ): Promise<SessionBindingServiceModule> {
@@ -207,6 +259,51 @@ describe("session binding service", () => {
     );
   });
 
+  it.each(["adapter-chat", "legacy-adapter-chat"])(
+    "distinguishes an unavailable %s owner from an empty result",
+    async (channel) => {
+      const service = getSessionBindingService();
+      const conversation = {
+        channel,
+        accountId: "default",
+        conversationId: "room-1",
+      };
+
+      expect(service.getCapabilities(conversation)).toEqual({
+        adapterAvailable: false,
+        bindSupported: false,
+        unbindSupported: false,
+        placements: [],
+      });
+      expect(inspectSessionBindingByConversation(conversation)).toEqual({
+        status: "unavailable",
+      });
+      await expectSessionBindingError(
+        service.bind({
+          targetSessionKey: "agent:finance:bound",
+          targetKind: "session",
+          conversation,
+        }),
+        "BINDING_ADAPTER_UNAVAILABLE",
+      );
+      const adapter: SessionBindingAdapter = {
+        channel,
+        accountId: "default",
+        listBySession: () => [],
+        resolveByConversation: () => null,
+      };
+      registerSessionBindingAdapter(adapter);
+      expect(inspectSessionBindingByConversation(conversation)).toEqual({
+        status: "available",
+        binding: null,
+      });
+      unregisterSessionBindingAdapter({ channel, accountId: "default", adapter });
+      expect(inspectSessionBindingByConversation(conversation)).toEqual({
+        status: "unavailable",
+      });
+    },
+  );
+
   it("returns structured errors for unsupported placement", async () => {
     registerSessionBindingAdapter({
       channel: "demo-binding",
diff --git a/src/infra/outbound/session-binding-service.ts b/src/infra/outbound/session-binding-service.ts
index 3fe7586d7d17..520b83e6fc73 100644
--- a/src/infra/outbound/session-binding-service.ts
+++ b/src/infra/outbound/session-binding-service.ts
@@ -7,6 +7,7 @@ import {
   bindGenericCurrentConversation,
   getGenericCurrentConversationBindingCapabilities,
   listGenericCurrentConversationBindingsBySession,
+  requiresRegisteredSessionBindingAdapter,
   resolveGenericCurrentConversationBinding,
   touchGenericCurrentConversationBinding,
   unbindGenericCurrentConversationBindings,
@@ -207,6 +208,28 @@ function dedupeBindings(records: SessionBindingRecord[]): SessionBindingRecord[]
   return [...byId.values()];
 }
 
+export function inspectSessionBindingByConversation(
+  ref: ConversationRef,
+): { status: "available"; binding: SessionBindingRecord | null } | { status: "unavailable" } {
+  const normalized = normalizeConversationRef(ref);
+  if (!normalized.channel || !normalized.conversationId) {
+    return { status: "available", binding: null };
+  }
+  const adapter = resolveAdapterForChannelAccount(normalized);
+  if (adapter) {
+    return { status: "available", binding: adapter.resolveByConversation(normalized) };
+  }
+  // A channel-owned adapter may disappear briefly during restart. That gap is not an
+  // authoritative empty result and must not let callers fall through to another owner.
+  if (requiresRegisteredSessionBindingAdapter(normalized)) {
+    return { status: "unavailable" };
+  }
+  return {
+    status: "available",
+    binding: resolveGenericCurrentConversationBinding(normalized),
+  };
+}
+
 function createDefaultSessionBindingService(): SessionBindingService {
   return {
     bind: async (input) => {
diff --git a/src/infra/state-migrations.media-persistence.historical-schema.test-support.ts b/src/infra/state-migrations.media-persistence.historical-schema.test-support.ts
index f4595ed60180..f93896c4a04f 100644
--- a/src/infra/state-migrations.media-persistence.historical-schema.test-support.ts
+++ b/src/infra/state-migrations.media-persistence.historical-schema.test-support.ts
@@ -43,6 +43,7 @@ export function historicalV15AgentSchemaSql(): string {
   let sql = restoreHistoricalAgentLeaseSchema(OPENCLAW_AGENT_SCHEMA_SQL)
     .replace("  entry_valid INTEGER NOT NULL DEFAULT 0 CHECK (entry_valid IN (-1, 0, 1)),\n", "")
     .replace("  project_id TEXT,\n", "")
+    .replace("  route_context_json TEXT,\n", "")
     .replace(
       "  owner_actor_type TEXT,\n  owner_actor_id TEXT,\n  owner_assigned_by_type TEXT,\n  owner_assigned_by_id TEXT,\n  owner_assigned_at INTEGER,\n",
       "",
@@ -57,6 +58,11 @@ export function historicalV15AgentSchemaSql(): string {
     "CREATE INDEX IF NOT EXISTS idx_agent_session_nodes_entry_valid_pending",
     "CREATE TABLE IF NOT EXISTS session_windows (",
   );
+  sql = removeSchemaRange(
+    sql,
+    "-- Older same-version writers preserve the envelope while updating the association.",
+    "CREATE INDEX IF NOT EXISTS idx_agent_session_conversations_conversation",
+  );
   sql = removeSchemaRange(
     sql,
     "CREATE TABLE IF NOT EXISTS message_tool_run_outcomes (",
diff --git a/src/plugin-sdk/conversation-binding-inspection-runtime.ts b/src/plugin-sdk/conversation-binding-inspection-runtime.ts
new file mode 100644
index 000000000000..7d8f01da7c76
--- /dev/null
+++ b/src/plugin-sdk/conversation-binding-inspection-runtime.ts
@@ -0,0 +1,20 @@
+import {
+  inspectSessionBindingByConversation,
+  type ConversationRef,
+  type SessionBindingRecord,
+} from "../infra/outbound/session-binding-service.js";
+
+/** Read-only result from the authoritative current-conversation binding store. */
+export type ConversationBindingInspection =
+  | { status: "available"; binding: SessionBindingRecord | null }
+  | { status: "unavailable" };
+
+/**
+ * Inspect current-conversation binding state without refreshing binding liveness.
+ * `unavailable` is distinct from an authoritative empty binding result.
+ */
+export function inspectConversationBinding(
+  conversation: ConversationRef,
+): ConversationBindingInspection {
+  return inspectSessionBindingByConversation(conversation);
+}
diff --git a/src/plugin-sdk/core.test.ts b/src/plugin-sdk/core.test.ts
index 59fa8f66bd25..42fdacd81600 100644
--- a/src/plugin-sdk/core.test.ts
+++ b/src/plugin-sdk/core.test.ts
@@ -226,4 +226,21 @@ describe("createChatChannelPlugin", () => {
       }),
     ).toBe(false);
   });
+
+  it("exports the conversation route-owner result contract", () => {
+    const messaging = {
+      resolveConversationRouteOwner: ({ conversation }) =>
+        conversation.peerId === "retry"
+          ? ({ kind: "unavailable" } as const)
+          : ({ kind: "agent", agentId: "main" } as const),
+    } satisfies NonNullable<ChannelPlugin["messaging"]>;
+
+    expect(
+      messaging.resolveConversationRouteOwner({
+        cfg: {},
+        accountId: "default",
+        conversation: { kind: "direct", peerId: "retry" },
+      }),
+    ).toEqual({ kind: "unavailable" });
+  });
 });
diff --git a/src/plugin-sdk/delivery-queue-runtime.ts b/src/plugin-sdk/delivery-queue-runtime.ts
index ef66e7e09ad7..a4a169cdcf8d 100644
--- a/src/plugin-sdk/delivery-queue-runtime.ts
+++ b/src/plugin-sdk/delivery-queue-runtime.ts
@@ -31,6 +31,12 @@ export async function drainPendingDeliveries(opts: DrainPendingDeliveriesOptions
     await drainPendingDeliveriesCore({
       ...opts,
       deliver,
+      // Conversation records belong to the Gateway recovery loop, which reconstructs current
+      // route authority before delivery. Plugin reconnect drains cannot safely consume them.
+      selectEntry: (entry, now) =>
+        entry.deliveryCompletion?.kind === "conversation"
+          ? { match: false, bypassBackoff: false }
+          : opts.selectEntry(entry, now),
     });
   });
 }
diff --git a/src/plugin-sdk/session-binding-runtime.ts b/src/plugin-sdk/session-binding-runtime.ts
index cce4abd67e5f..c98a86ceb85a 100644
--- a/src/plugin-sdk/session-binding-runtime.ts
+++ b/src/plugin-sdk/session-binding-runtime.ts
@@ -4,6 +4,7 @@ export {
   testing as __testing,
   testing,
   getSessionBindingService,
+  inspectSessionBindingByConversation,
   registerSessionBindingAdapter,
   type SessionBindingRecord,
   type SessionBindingService,
diff --git a/src/plugins/channel-registry-state.types.ts b/src/plugins/channel-registry-state.types.ts
index 659ce0bd50d8..9183a8506197 100644
--- a/src/plugins/channel-registry-state.types.ts
+++ b/src/plugins/channel-registry-state.types.ts
@@ -8,6 +8,7 @@ export type ActiveChannelPluginRuntimeShape = {
   } | null;
   messaging?: {
     targetPrefixes?: readonly string[];
+    resolveConversationRouteOwner?: (...args: never[]) => unknown;
   } | null;
   capabilities?: {
     nativeCommands?: boolean;
@@ -15,6 +16,8 @@ export type ActiveChannelPluginRuntimeShape = {
   conversationBindings?: {
     supportsCurrentConversationBinding?: boolean;
     isCurrentConversationBindingSupported?: (params: { accountId: string }) => boolean;
+    bindingStore?: "adapter";
+    createManager?: unknown;
   } | null;
 };
 
diff --git a/src/state/openclaw-agent-db-schema-helpers.ts b/src/state/openclaw-agent-db-schema-helpers.ts
index 8f3bc49dfe6a..9400b440babe 100644
--- a/src/state/openclaw-agent-db-schema-helpers.ts
+++ b/src/state/openclaw-agent-db-schema-helpers.ts
@@ -27,8 +27,8 @@ import { FIRST_USE_ADDITIVE_AGENT_COLUMN_DEFINITIONS } from "./openclaw-agent-db
 import { OPENCLAW_AGENT_SCHEMA_VERSION } from "./openclaw-agent-db-contract.js";
 import { OpenClawAgentDatabaseMediaMigrationRequiredError } from "./openclaw-agent-db-migration-required.js";
 import {
+  ensureSessionAdditiveColumns,
   ensureSessionEntryValidityProjection,
-  ensureSessionProjectColumn,
 } from "./openclaw-agent-db-session-migrations.js";
 import { MESSAGE_TOOL_RUN_OUTCOMES_TABLE } from "./openclaw-agent-message-tool-outcome-schema.js";
 import {
@@ -71,6 +71,7 @@ const AGENT_SCHEMA_COMPATIBILITY = {
     ...STANDING_INTENTS_FTS_SHADOW_TABLES,
   ],
   allowedMissingColumns: [
+    "session_conversations.route_context_json",
     "session_participants.actor_source",
     "standing_intents.creator_sender",
     ...FIRST_USE_ADDITIVE_AGENT_COLUMN_DEFINITIONS.map(
@@ -189,7 +190,7 @@ export function repairAndAssertOpenClawAgentV14SchemaForMigration(
     );
   }
 
-  ensureSessionProjectColumn(database);
+  ensureSessionAdditiveColumns(database);
   ensureSessionEntryValidityProjection(database);
   ensureSessionKeyContractSchemaInTransaction(database);
 
diff --git a/src/state/openclaw-agent-db-schema.ts b/src/state/openclaw-agent-db-schema.ts
index a8d6f6e08c7e..acf5fa1cf5ed 100644
--- a/src/state/openclaw-agent-db-schema.ts
+++ b/src/state/openclaw-agent-db-schema.ts
@@ -42,8 +42,9 @@ import {
 } from "./openclaw-agent-db-schema-helpers.js";
 import {
   backfillSessionConversations,
-  ensureSessionProjectColumn,
+  ensureSessionAdditiveColumns,
   ensureSessionEntryValidityProjection,
+  hasPendingSessionConversationRouteContextColumn,
   migrateConversationDeliveryTargetColumn,
   migrateSessionEntryStatusProjection,
   readSqliteTableColumns,
@@ -569,6 +570,7 @@ export function assertAgentDatabaseIntegrityBeforeMutation(
     (hasPendingMemoryChunkMetadataMigration(database) ||
       hasPendingSessionKeyContractSchemaMigration(database) ||
       hasRetiredAgentStateLeaseSchema(database) ||
+      hasPendingSessionConversationRouteContextColumn(database) ||
       hasPendingSessionProjectColumn(database));
   if (userVersion === OPENCLAW_AGENT_SCHEMA_VERSION && !hasPendingCurrentVersionMigration) {
     verifyAndRepairCanonicalSqliteIndexes(database, pathname, OPENCLAW_AGENT_SCHEMA_SQL, {
@@ -628,7 +630,7 @@ function ensureAgentSchema(
       }
       migrateRetiredAgentStateLeaseSchema(db, pathname, targetVersion);
       if (previousVersion === targetVersion) {
-        ensureSessionProjectColumn(db);
+        ensureSessionAdditiveColumns(db);
         ensureSessionEntryValidityProjection(db);
         ensureSessionKeyContractSchemaInTransaction(db);
         if (hasPendingMemoryChunkMetadataMigration(db)) {
@@ -663,7 +665,7 @@ function ensureAgentSchema(
       }
       backfillSessionEntryProvenance(db, previousVersion);
       migrateSessionNodesAndWindows(db, previousVersion);
-      ensureSessionProjectColumn(db);
+      ensureSessionAdditiveColumns(db);
       ensureSessionEntryValidityProjection(db);
       db.exec(OPENCLAW_AGENT_SCHEMA_SQL);
       migrateMemoryChunkMetadataSchema(db);
diff --git a/src/state/openclaw-agent-db-session-migrations.test.ts b/src/state/openclaw-agent-db-session-migrations.test.ts
index 8dfc38e9dfa2..78477151048f 100644
--- a/src/state/openclaw-agent-db-session-migrations.test.ts
+++ b/src/state/openclaw-agent-db-session-migrations.test.ts
@@ -3,6 +3,7 @@ import { requireNodeSqlite } from "../infra/node-sqlite.js";
 import { buildConversationRef } from "../routing/conversation-ref.js";
 import {
   backfillSessionConversations,
+  ensureSessionAdditiveColumns,
   migrateConversationDeliveryTargetColumn,
 } from "./openclaw-agent-db-session-migrations.js";
 
@@ -15,6 +16,72 @@ describe("agent DB conversation migration", () => {
     }
   });
 
+  it("adds nullable route context without advancing the schema version", () => {
+    const sqlite = requireNodeSqlite();
+    const database = new sqlite.DatabaseSync(":memory:");
+    databases.push(database);
+    database.exec(`
+      PRAGMA user_version = 17;
+      CREATE TABLE session_conversations (
+        session_id TEXT NOT NULL,
+        conversation_id TEXT NOT NULL,
+        role TEXT NOT NULL,
+        first_seen_at INTEGER NOT NULL,
+        last_seen_at INTEGER NOT NULL,
+        PRIMARY KEY (session_id, conversation_id, role)
+      ) STRICT;
+      INSERT INTO session_conversations (
+        session_id, conversation_id, role, first_seen_at, last_seen_at
+      ) VALUES ('session-a', 'conversation-a', 'primary', 1, 1);
+    `);
+
+    ensureSessionAdditiveColumns(database);
+    ensureSessionAdditiveColumns(database);
+    database
+      .prepare(
+        "UPDATE session_conversations SET route_context_json = ? WHERE session_id = ? AND conversation_id = ?",
+      )
+      .run(
+        '{"version":1,"writeId":"candidate-write","observedAt":1,"context":{"guildId":"guild-a"}}',
+        "session-a",
+        "conversation-a",
+      );
+    database
+      .prepare(
+        "UPDATE session_conversations SET route_context_json = ?, last_seen_at = ? WHERE session_id = ? AND conversation_id = ?",
+      )
+      .run(
+        '{"version":1,"writeId":"current-write","observedAt":1,"context":{"guildId":"guild-a"}}',
+        1,
+        "session-a",
+        "conversation-a",
+      );
+    expect(
+      database
+        .prepare(
+          "SELECT route_context_json FROM session_conversations WHERE session_id = 'session-a'",
+        )
+        .get(),
+    ).toEqual({
+      route_context_json:
+        '{"version":1,"writeId":"current-write","observedAt":1,"context":{"guildId":"guild-a"}}',
+    });
+    database
+      .prepare(
+        "UPDATE session_conversations SET last_seen_at = ? WHERE session_id = ? AND conversation_id = ?",
+      )
+      .run(1, "session-a", "conversation-a");
+
+    expect(database.prepare("PRAGMA user_version").get()).toEqual({ user_version: 17 });
+    expect(
+      database
+        .prepare(
+          "SELECT route_context_json, last_seen_at FROM session_conversations WHERE session_id = 'session-a'",
+        )
+        .get(),
+    ).toEqual({ route_context_json: null, last_seen_at: 1 });
+  });
+
   it("backfills direct addresses and keeps shared-main peers as participants", () => {
     const sqlite = requireNodeSqlite();
     const database = new sqlite.DatabaseSync(":memory:");
diff --git a/src/state/openclaw-agent-db-session-migrations.ts b/src/state/openclaw-agent-db-session-migrations.ts
index 59401dbab9bc..19415e330a08 100644
--- a/src/state/openclaw-agent-db-session-migrations.ts
+++ b/src/state/openclaw-agent-db-session-migrations.ts
@@ -127,6 +127,7 @@ export function backfillSessionConversations(db: DatabaseSync): void {
         session_id TEXT NOT NULL,
         conversation_id TEXT NOT NULL,
         role TEXT NOT NULL DEFAULT 'primary' CHECK (role IN ('primary', 'participant', 'related')),
+        route_context_json TEXT,
         first_seen_at INTEGER NOT NULL,
         last_seen_at INTEGER NOT NULL,
         PRIMARY KEY (session_id, conversation_id, role),
@@ -269,13 +270,37 @@ export function readSqliteTableColumns(db: DatabaseSync, tableName: string): Set
   return new Set(rows.flatMap((row) => (typeof row.name === "string" ? [row.name] : [])));
 }
 
-/** Installs the same-version project identity projection on first updated-binary open. */
-export function ensureSessionProjectColumn(db: DatabaseSync): void {
+/** Installs same-version session projections on first updated-binary open. */
+export function ensureSessionAdditiveColumns(db: DatabaseSync): void {
   const columns = readSqliteTableColumns(db, "session_nodes");
-  if (!columns || columns.has("project_id")) {
-    return;
+  if (columns && !columns.has("project_id")) {
+    db.exec("ALTER TABLE session_nodes ADD COLUMN project_id TEXT;");
   }
-  db.exec("ALTER TABLE session_nodes ADD COLUMN project_id TEXT;");
+  const conversationColumns = readSqliteTableColumns(db, "session_conversations");
+  if (conversationColumns && !conversationColumns.has("route_context_json")) {
+    db.exec("ALTER TABLE session_conversations ADD COLUMN route_context_json TEXT");
+  }
+  if (conversationColumns) {
+    // Same-version older writers leave the envelope byte-identical. Clear it on their update so
+    // stale owner facts cannot survive a downgrade/re-upgrade cycle with an unchanged timestamp.
+    db.exec(`
+      CREATE TRIGGER IF NOT EXISTS session_conversations_route_context_invalidate_after_update
+      AFTER UPDATE OF role, last_seen_at ON session_conversations
+      WHEN NEW.route_context_json IS OLD.route_context_json
+      BEGIN
+        UPDATE session_conversations
+        SET route_context_json = NULL
+        WHERE session_id = NEW.session_id
+          AND conversation_id = NEW.conversation_id
+          AND role = NEW.role;
+      END;
+    `);
+  }
+}
+
+export function hasPendingSessionConversationRouteContextColumn(db: DatabaseSync): boolean {
+  const columns = readSqliteTableColumns(db, "session_conversations");
+  return Boolean(columns && !columns.has("route_context_json"));
 }
 
 /** Adds the v11 exact delivery target before the conversation backfill writes canonical rows. */
diff --git a/src/state/openclaw-agent-db.generated.d.ts b/src/state/openclaw-agent-db.generated.d.ts
index da9e2882f43c..2d9184033329 100644
--- a/src/state/openclaw-agent-db.generated.d.ts
+++ b/src/state/openclaw-agent-db.generated.d.ts
@@ -221,6 +221,7 @@ export interface SessionConversations {
   first_seen_at: number;
   last_seen_at: number;
   role: Generated<string>;
+  route_context_json: string | null;
   session_id: string;
 }
 
diff --git a/src/state/openclaw-agent-db.test.ts b/src/state/openclaw-agent-db.test.ts
index 39402ba044a4..d91291164046 100644
--- a/src/state/openclaw-agent-db.test.ts
+++ b/src/state/openclaw-agent-db.test.ts
@@ -3490,9 +3490,11 @@ describe("openclaw agent database", () => {
         DROP TRIGGER session_nodes_entry_valid_after_insert;
         DROP TRIGGER session_nodes_entry_valid_after_entry_update;
         DROP TRIGGER session_nodes_entry_valid_after_identity_update;
+        DROP TRIGGER session_conversations_route_context_invalidate_after_update;
         DROP INDEX idx_agent_session_nodes_entry_valid_pending;
         DROP TABLE session_key_contract;
         ALTER TABLE session_nodes DROP COLUMN entry_valid;
+        ALTER TABLE session_conversations DROP COLUMN route_context_json;
       `);
       expect(readSqliteNumberPragma(shippedSchema, "user_version")).toBe(
         OPENCLAW_AGENT_SCHEMA_VERSION,
@@ -3515,6 +3517,13 @@ describe("openclaw agent database", () => {
     expect(
       repaired.db.prepare("SELECT main_key FROM session_key_contract WHERE id = 1").get(),
     ).toEqual({ main_key: "main" });
+    expect(
+      repaired.db
+        .prepare(
+          "SELECT name FROM pragma_table_info('session_conversations') WHERE name = 'route_context_json'",
+        )
+        .get(),
+    ).toEqual({ name: "route_context_json" });
   });
 
   it("installs same-version session additions before maintenance index repair", () => {
diff --git a/src/state/openclaw-agent-schema.sql b/src/state/openclaw-agent-schema.sql
index a87b195f6e30..c41d257bf30d 100644
--- a/src/state/openclaw-agent-schema.sql
+++ b/src/state/openclaw-agent-schema.sql
@@ -219,6 +219,7 @@ CREATE TABLE IF NOT EXISTS session_conversations (
   session_id TEXT NOT NULL,
   conversation_id TEXT NOT NULL,
   role TEXT NOT NULL DEFAULT 'primary' CHECK (role IN ('primary', 'participant', 'related')),
+  route_context_json TEXT,
   first_seen_at INTEGER NOT NULL,
   last_seen_at INTEGER NOT NULL,
   PRIMARY KEY (session_id, conversation_id, role),
@@ -226,6 +227,18 @@ CREATE TABLE IF NOT EXISTS session_conversations (
   FOREIGN KEY (conversation_id) REFERENCES conversations(conversation_id) ON DELETE CASCADE
 ) STRICT;
 
+-- Older same-version writers preserve the envelope while updating the association.
+CREATE TRIGGER IF NOT EXISTS session_conversations_route_context_invalidate_after_update
+AFTER UPDATE OF role, last_seen_at ON session_conversations
+WHEN NEW.route_context_json IS OLD.route_context_json
+BEGIN
+  UPDATE session_conversations
+  SET route_context_json = NULL
+  WHERE session_id = NEW.session_id
+    AND conversation_id = NEW.conversation_id
+    AND role = NEW.role;
+END;
+
 CREATE INDEX IF NOT EXISTS idx_agent_session_conversations_conversation
   ON session_conversations(conversation_id, last_seen_at DESC, session_id);
 
diff --git a/test/e2e/qa-lab/runtime/conversation-route-ownership.e2e.test.ts b/test/e2e/qa-lab/runtime/conversation-route-ownership.e2e.test.ts
new file mode 100644
index 000000000000..a88501a0532d
--- /dev/null
+++ b/test/e2e/qa-lab/runtime/conversation-route-ownership.e2e.test.ts
@@ -0,0 +1,337 @@
+import { randomUUID } from "node:crypto";
+import { isRecord } from "@openclaw/normalization-core/record-coerce";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  createQaBusState,
+  createQaChannelTransport,
+  startQaBusServer,
+} from "../../../../extensions/qa-lab/api.js";
+import { startQaLiveLaneGateway } from "../../../../extensions/qa-lab/runtime-api.js";
+
+const CHANNEL_ID = "qa-channel";
+const PRIMARY_AGENT_ID = "main";
+const SIBLING_AGENT_ID = "finance";
+const PRIMARY_ACCOUNT_ID = "default";
+const SIBLING_ACCOUNT_ID = "finance";
+const PRIMARY_PEER_ID = "primary-peer";
+const SIBLING_PEER_ID = "finance-peer";
+
+type GatewayHarness = Awaited<ReturnType<typeof startQaLiveLaneGateway>>;
+
+let harness: GatewayHarness | undefined;
+let bus: Awaited<ReturnType<typeof startQaBusServer>> | undefined;
+
+function conversationItems(payload: unknown): Array<Record<string, unknown>> {
+  if (!isRecord(payload) || !Array.isArray(payload.conversations)) {
+    throw new Error(`conversations.list returned an invalid payload: ${JSON.stringify(payload)}`);
+  }
+  const items = payload.conversations.filter(isRecord);
+  if (items.length !== payload.conversations.length) {
+    throw new Error(`conversations.list returned an invalid item: ${JSON.stringify(payload)}`);
+  }
+  return items;
+}
+
+function findConversation(
+  items: Array<Record<string, unknown>>,
+  accountId: string,
+  targetIncludes: string,
+) {
+  return items.find(
+    (item) =>
+      item.accountId === accountId &&
+      typeof item.target === "string" &&
+      item.target.includes(targetIncludes),
+  );
+}
+
+async function listConversations(gateway: GatewayHarness["gateway"], agentId: string) {
+  return conversationItems(
+    await gateway.call("conversations.list", {
+      agentId,
+      channel: CHANNEL_ID,
+      limit: 50,
+    }),
+  );
+}
+
+async function waitForConversation(params: {
+  gateway: GatewayHarness["gateway"];
+  agentId: string;
+  accountId: string;
+  targetIncludes: string;
+}) {
+  const deadline = Date.now() + 30_000;
+  let latest: Array<Record<string, unknown>> = [];
+  while (Date.now() < deadline) {
+    latest = await listConversations(params.gateway, params.agentId);
+    const match = findConversation(latest, params.accountId, params.targetIncludes);
+    if (match) {
+      return match;
+    }
+    await new Promise<void>((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(
+    `timed out waiting for ${params.agentId} to own ${params.accountId}/${params.targetIncludes}: ${JSON.stringify(latest)}`,
+  );
+}
+
+async function waitForAppliedConfig(gateway: GatewayHarness["gateway"], hash: string) {
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    const payload = await gateway.call("config.get", {});
+    if (
+      isRecord(payload) &&
+      payload.hash === hash &&
+      payload.appliedConfigHash === payload.configRevisionHash
+    ) {
+      return;
+    }
+    await new Promise<void>((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(`Gateway did not apply config revision ${hash}`);
+}
+
+function outboundMessagesWithText(
+  state: ReturnType<typeof createQaBusState>,
+  accountId: string,
+  text: string,
+) {
+  return state
+    .getSnapshot()
+    .messages.filter(
+      (message) =>
+        message.direction === "outbound" &&
+        message.accountId === accountId &&
+        message.text === text,
+    );
+}
+
+async function sendConversation(params: {
+  gateway: GatewayHarness["gateway"];
+  agentId: string;
+  conversationRef: string;
+  message: string;
+}) {
+  return await params.gateway.call("conversations.send", {
+    agentId: params.agentId,
+    operationId: randomUUID(),
+    conversationRef: params.conversationRef,
+    message: params.message,
+  });
+}
+
+afterEach(async () => {
+  const cleanupErrors: unknown[] = [];
+  try {
+    await harness?.stop();
+  } catch (error) {
+    cleanupErrors.push(error);
+  } finally {
+    harness = undefined;
+  }
+  try {
+    await bus?.stop();
+  } catch (error) {
+    cleanupErrors.push(error);
+  } finally {
+    bus = undefined;
+  }
+  if (cleanupErrors.length > 0) {
+    throw new AggregateError(cleanupErrors, "conversation route ownership proof cleanup failed");
+  }
+});
+
+describe("conversation route ownership clean-machine proof", () => {
+  it(
+    "keeps sibling accounts isolated and revalidates persisted references after reassignment",
+    { timeout: 120_000 },
+    async () => {
+      const state = createQaBusState();
+      const transport = createQaChannelTransport(state);
+      bus = await startQaBusServer({ state });
+      harness = await startQaLiveLaneGateway({
+        repoRoot: process.cwd(),
+        providerMode: "mock-openai",
+        primaryModel: "mock-openai/gpt-5.6-luna",
+        alternateModel: "mock-openai/gpt-5.6-luna-alt",
+        transport,
+        transportBaseUrl: bus.baseUrl,
+        controlUiEnabled: false,
+        mockAuthAgentIds: [PRIMARY_AGENT_ID, SIBLING_AGENT_ID],
+        mutateConfig: (config) => ({
+          ...config,
+          agents: {
+            ...config.agents,
+            ownership: "explicit",
+            entries: {
+              ...config.agents?.entries,
+              [PRIMARY_AGENT_ID]: {},
+              [SIBLING_AGENT_ID]: {},
+            },
+          },
+          bindings: [
+            {
+              type: "route",
+              agentId: PRIMARY_AGENT_ID,
+              match: { channel: CHANNEL_ID, accountId: PRIMARY_ACCOUNT_ID },
+            },
+            {
+              type: "route",
+              agentId: SIBLING_AGENT_ID,
+              match: { channel: CHANNEL_ID, accountId: SIBLING_ACCOUNT_ID },
+            },
+          ],
+          channels: {
+            ...config.channels,
+            [CHANNEL_ID]: {
+              ...config.channels?.[CHANNEL_ID],
+              accounts: {
+                [SIBLING_ACCOUNT_ID]: {
+                  baseUrl: bus?.baseUrl,
+                  enabled: true,
+                  allowFrom: ["*"],
+                  pollTimeoutMs: 250,
+                },
+              },
+            },
+          },
+        }),
+      });
+      const { gateway } = harness;
+
+      state.addInboundMessage({
+        accountId: PRIMARY_ACCOUNT_ID,
+        conversation: { kind: "direct", id: PRIMARY_PEER_ID },
+        senderId: PRIMARY_PEER_ID,
+        text: "seed primary ownership",
+      });
+      state.addInboundMessage({
+        accountId: SIBLING_ACCOUNT_ID,
+        conversation: { kind: "direct", id: SIBLING_PEER_ID },
+        senderId: SIBLING_PEER_ID,
+        text: "seed sibling ownership",
+      });
+
+      const primaryConversation = await waitForConversation({
+        gateway,
+        agentId: PRIMARY_AGENT_ID,
+        accountId: PRIMARY_ACCOUNT_ID,
+        targetIncludes: PRIMARY_PEER_ID,
+      });
+      const siblingConversation = await waitForConversation({
+        gateway,
+        agentId: SIBLING_AGENT_ID,
+        accountId: SIBLING_ACCOUNT_ID,
+        targetIncludes: SIBLING_PEER_ID,
+      });
+      const primaryList = await listConversations(gateway, PRIMARY_AGENT_ID);
+      const siblingList = await listConversations(gateway, SIBLING_AGENT_ID);
+      expect(findConversation(primaryList, SIBLING_ACCOUNT_ID, SIBLING_PEER_ID)).toBeUndefined();
+      expect(findConversation(siblingList, PRIMARY_ACCOUNT_ID, PRIMARY_PEER_ID)).toBeUndefined();
+
+      const primaryConversationRef = String(primaryConversation.conversationRef);
+      const siblingConversationRef = String(siblingConversation.conversationRef);
+      const initialAllowedText = `ownership-proof-initial-${randomUUID()}`;
+      await sendConversation({
+        gateway,
+        agentId: PRIMARY_AGENT_ID,
+        conversationRef: primaryConversationRef,
+        message: initialAllowedText,
+      });
+      expect(outboundMessagesWithText(state, PRIMARY_ACCOUNT_ID, initialAllowedText)).toHaveLength(
+        1,
+      );
+
+      const configBefore = await gateway.call("config.get", {});
+      if (!isRecord(configBefore) || typeof configBefore.hash !== "string") {
+        throw new Error(`config.get returned no hash: ${JSON.stringify(configBefore)}`);
+      }
+      const patchResult = await gateway.call("config.patch", {
+        raw: JSON.stringify({
+          bindings: [
+            {
+              type: "route",
+              agentId: SIBLING_AGENT_ID,
+              match: { channel: CHANNEL_ID, accountId: PRIMARY_ACCOUNT_ID },
+            },
+            {
+              type: "route",
+              agentId: SIBLING_AGENT_ID,
+              match: { channel: CHANNEL_ID, accountId: SIBLING_ACCOUNT_ID },
+            },
+          ],
+        }),
+        baseHash: configBefore.hash,
+        replacePaths: ["bindings"],
+        restartDelayMs: 0,
+      });
+      if (!isRecord(patchResult) || typeof patchResult.hash !== "string") {
+        throw new Error(`config.patch returned no hash: ${JSON.stringify(patchResult)}`);
+      }
+      await waitForAppliedConfig(gateway, patchResult.hash);
+
+      const staleSendText = `ownership-proof-stale-send-${randomUUID()}`;
+      let staleSendDenied = false;
+      try {
+        await sendConversation({
+          gateway,
+          agentId: PRIMARY_AGENT_ID,
+          conversationRef: primaryConversationRef,
+          message: staleSendText,
+        });
+      } catch {
+        staleSendDenied = true;
+      }
+      expect(staleSendDenied).toBe(true);
+      expect(outboundMessagesWithText(state, PRIMARY_ACCOUNT_ID, staleSendText)).toHaveLength(0);
+
+      const staleTurnText = `ownership-proof-stale-turn-${randomUUID()}`;
+      let staleTurnDenied = false;
+      try {
+        await gateway.call("conversations.turn", {
+          agentId: PRIMARY_AGENT_ID,
+          turnId: randomUUID(),
+          conversationRef: primaryConversationRef,
+          message: staleTurnText,
+          timeoutMs: 1_000,
+        });
+      } catch {
+        staleTurnDenied = true;
+      }
+      expect(staleTurnDenied).toBe(true);
+      expect(outboundMessagesWithText(state, PRIMARY_ACCOUNT_ID, staleTurnText)).toHaveLength(0);
+
+      const siblingAllowedText = `ownership-proof-sibling-${randomUUID()}`;
+      await sendConversation({
+        gateway,
+        agentId: SIBLING_AGENT_ID,
+        conversationRef: siblingConversationRef,
+        message: siblingAllowedText,
+      });
+      expect(outboundMessagesWithText(state, SIBLING_ACCOUNT_ID, siblingAllowedText)).toHaveLength(
+        1,
+      );
+
+      const verdict = {
+        ok: true,
+        siblingAccountHiddenFromPrimaryAgent:
+          findConversation(primaryList, SIBLING_ACCOUNT_ID, SIBLING_PEER_ID) === undefined,
+        primaryAccountHiddenFromSiblingAgent:
+          findConversation(siblingList, PRIMARY_ACCOUNT_ID, PRIMARY_PEER_ID) === undefined,
+        initialOwnerDeliveredExactlyOnce:
+          outboundMessagesWithText(state, PRIMARY_ACCOUNT_ID, initialAllowedText).length === 1,
+        staleSendDeniedWithoutProviderIo:
+          staleSendDenied &&
+          outboundMessagesWithText(state, PRIMARY_ACCOUNT_ID, staleSendText).length === 0,
+        staleTurnDeniedWithoutProviderIo:
+          staleTurnDenied &&
+          outboundMessagesWithText(state, PRIMARY_ACCOUNT_ID, staleTurnText).length === 0,
+        siblingOwnerDeliveredExactlyOnce:
+          outboundMessagesWithText(state, SIBLING_ACCOUNT_ID, siblingAllowedText).length === 1,
+      };
+      expect(Object.values(verdict).every(Boolean)).toBe(true);
+      console.log(`CONVERSATION_ROUTE_OWNERSHIP_PROOF=${JSON.stringify(verdict)}`);
+    },
+  );
+});
diff --git a/test/release-check.test.ts b/test/release-check.test.ts
index 3e3804269629..959f80044281 100644
--- a/test/release-check.test.ts
+++ b/test/release-check.test.ts
@@ -885,6 +885,7 @@ describe("createPackedPluginSdkTypescriptSmokeProject", () => {
       expect(source).toContain('"openclaw/plugin-sdk/channel-entry-contract"');
       expect(source).toContain('"openclaw/plugin-sdk/config-contracts"');
       expect(source).toContain('"openclaw/plugin-sdk/runtime-env"');
+      expect(source).toContain('"openclaw/plugin-sdk/conversation-binding-inspection-runtime"');
       expect(source).toContain("type PublicPluginSdkModules = [");
       expect(source).not.toContain("TelegramAccountConfig");
       expect(source).not.toContain("openclaw/plugin-sdk/channel-contract-testing");

From 4573635c77f9807be186bd4dbde227e5bfe7e4cc Mon Sep 17 00:00:00 2001
From: pash-openai <pash@openai.com>
Date: Fri, 21 Aug 2026 12:30:54 -0700
Subject: [PATCH 078/124] Let Codex use newly available account models before
 catalog refresh (#127394)

* Let Codex run newly available account models without host credentials

* Keep authored provider routes ahead of native account authentication

* Keep native Codex account discovery consistent with model availability

* Preserve advanced reasoning for newly discovered Codex models
---
 extensions/codex/harness.test.ts             | 11 ++++
 extensions/codex/harness.ts                  |  6 +-
 extensions/openai/openai-chatgpt-provider.ts | 21 ++++++
 extensions/openai/openai-provider.test.ts    | 68 ++++++++++++++++++++
 extensions/openai/thinking-policy.ts         |  9 +++
 src/agents/model-auth-availability.test.ts   |  9 +++
 src/agents/model-auth-availability.ts        |  4 ++
 src/agents/openai-model-routes.ts            |  1 +
 src/agents/provider-model-route-auth.test.ts | 30 +++++++++
 src/agents/provider-model-route-auth.ts      | 13 +++-
 src/agents/runtime-plan/prepare-auth.ts      |  3 +
 11 files changed, 171 insertions(+), 4 deletions(-)

diff --git a/extensions/codex/harness.test.ts b/extensions/codex/harness.test.ts
index c387732d9ebf..ef24f197506b 100644
--- a/extensions/codex/harness.test.ts
+++ b/extensions/codex/harness.test.ts
@@ -262,6 +262,17 @@ describe("Codex agent harness supports()", () => {
     ).toEqual({ supported: true, priority: 100 });
   });
 
+  it("lets explicit Codex model discovery run before auth has been prepared", () => {
+    expect(
+      harness.supports({
+        provider: "openai",
+        modelId: "gpt-future",
+        requestedRuntime: "codex",
+        modelProvider: { requestTransportOverrides: "none" },
+      }),
+    ).toEqual({ supported: true, priority: 100 });
+  });
+
   it.each([
     {
       label: "automatic runtime selection",
diff --git a/extensions/codex/harness.ts b/extensions/codex/harness.ts
index 8fdb1698da98..942e6ab55077 100644
--- a/extensions/codex/harness.ts
+++ b/extensions/codex/harness.ts
@@ -210,9 +210,9 @@ export function createCodexAppServerAgentHarness(
         provider === "openai" &&
         ctx.requestedRuntime === "codex" &&
         Boolean(ctx.modelId?.trim()) &&
-        preparedAuth?.source === "harness" &&
-        preparedAuth.mode === undefined &&
-        preparedAuth.requirement === undefined &&
+        (preparedAuth === undefined || preparedAuth.source === "harness") &&
+        preparedAuth?.mode === undefined &&
+        preparedAuth?.requirement === undefined &&
         ctx.modelProvider?.api === undefined &&
         ctx.modelProvider?.baseUrl === undefined &&
         ctx.modelProvider?.azureApiVersion === undefined &&
diff --git a/extensions/openai/openai-chatgpt-provider.ts b/extensions/openai/openai-chatgpt-provider.ts
index abc8cffb168d..148e69e43617 100644
--- a/extensions/openai/openai-chatgpt-provider.ts
+++ b/extensions/openai/openai-chatgpt-provider.ts
@@ -327,6 +327,25 @@ function resolveCodexForwardCompatModel(ctx: ProviderResolveDynamicModelContext)
       maxTokens: OPENAI_CODEX_GPT_54_MAX_TOKENS,
       cost: OPENAI_CODEX_GPT_54_MINI_COST,
     };
+  } else if (
+    ctx.agentRuntimeId === "codex" &&
+    ctx.authProfileId === undefined &&
+    ctx.authProfileMode === undefined &&
+    ctx.providerConfig?.auth === undefined
+  ) {
+    // Codex owns its account-scoped model catalog. When that catalog is not yet
+    // available, keep the requested identity intact and let the native runtime
+    // decide whether the account can actually use it.
+    templateIds = OPENAI_CODEX_GPT_56_MODEL_IDS;
+    patch = {
+      reasoning: true,
+      input: ["text", "image"],
+      thinkingLevelMap: OPENAI_CODEX_GPT_56_THINKING_LEVEL_MAP,
+      compat: {
+        supportsReasoningEffort: true,
+        supportedReasoningEfforts: ["low", "medium", "high", "xhigh", "max"],
+      },
+    };
   } else {
     return undefined;
   }
@@ -365,6 +384,8 @@ function resolveCodexForwardCompatModel(ctx: ProviderResolveDynamicModelContext)
       contextWindow: patch?.contextWindow ?? DEFAULT_CONTEXT_TOKENS,
       contextTokens: patch?.contextTokens,
       maxTokens: patch?.maxTokens ?? DEFAULT_CONTEXT_TOKENS,
+      ...(patch?.thinkingLevelMap ? { thinkingLevelMap: patch.thinkingLevelMap } : {}),
+      ...(patch?.compat ? { compat: patch.compat } : {}),
     } as ProviderRuntimeModel)
   );
 }
diff --git a/extensions/openai/openai-provider.test.ts b/extensions/openai/openai-provider.test.ts
index 828469f6a9a3..ffafd1088f8a 100644
--- a/extensions/openai/openai-provider.test.ts
+++ b/extensions/openai/openai-provider.test.ts
@@ -1766,6 +1766,74 @@ describe("buildOpenAIProvider", () => {
     ).toEqual({ effort: "high", transport: "sse" });
   });
 
+  it("delegates an unlisted first-party model to its explicitly selected Codex runtime", () => {
+    const provider = buildOpenAIProvider();
+    const model = provider.resolveDynamicModel?.({
+      provider: "openai",
+      modelId: "gpt-future",
+      modelRegistry: { find: () => null },
+      agentRuntimeId: "codex",
+    } as never);
+
+    expect(model).toMatchObject({
+      provider: "openai",
+      id: "gpt-future",
+      api: "openai-chatgpt-responses",
+      baseUrl: "https://chatgpt.com/backend-api/codex",
+      compat: { supportedReasoningEfforts: ["low", "medium", "high", "xhigh", "max"] },
+    });
+    expect(
+      provider
+        .resolveThinkingProfile?.({
+          provider: "openai",
+          modelId: "gpt-future",
+          agentRuntime: "codex",
+          api: model?.api,
+          compat: model?.compat,
+        } as never)
+        ?.levels.map((level) => level.id),
+    ).toContain("max");
+    expect(
+      provider
+        .resolveThinkingProfile?.({
+          provider: "openai",
+          modelId: "gpt-future",
+          agentRuntime: "codex",
+        } as never)
+        ?.levels.map((level) => level.id),
+    ).toEqual(expect.arrayContaining(["xhigh", "max"]));
+  });
+
+  it("does not invent an unlisted model for authored Platform credentials", () => {
+    const provider = buildOpenAIProvider();
+
+    expect(
+      provider.resolveDynamicModel?.({
+        provider: "openai",
+        modelId: "gpt-future",
+        modelRegistry: { find: () => null },
+        agentRuntimeId: "codex",
+        authProfileId: "openai:platform",
+        authProfileMode: "api_key",
+        providerConfig: {
+          auth: "api-key",
+          api: "openai-responses",
+          baseUrl: "https://api.openai.com/v1",
+        },
+      } as never),
+    ).toBeUndefined();
+    expect(
+      provider
+        .resolveThinkingProfile?.({
+          provider: "openai",
+          modelId: "gpt-future",
+          agentRuntime: "codex",
+          api: "openai-responses",
+        } as never)
+        ?.levels.map((level) => level.id),
+    ).not.toContain("max");
+  });
+
   it("restores gpt-5.3-codex-spark only through ChatGPT/Codex OAuth routing", () => {
     const provider = buildOpenAIProvider();
 
diff --git a/extensions/openai/thinking-policy.ts b/extensions/openai/thinking-policy.ts
index 648ef4feccaf..a354e5565e01 100644
--- a/extensions/openai/thinking-policy.ts
+++ b/extensions/openai/thinking-policy.ts
@@ -110,6 +110,12 @@ function buildOpenAIThinkingProfile(params: {
     (agentRuntime === "openclaw" ||
       agentRuntime === "auto" ||
       (agentRuntime === "codex" && codexSupportsUltra));
+  const nativeCodexNeedsAccountEffortValidation =
+    agentRuntime === "codex" &&
+    params.compat?.supportedReasoningEfforts === undefined &&
+    (params.api === undefined || params.api === "openai-chatgpt-responses") &&
+    !matchesExactOrPrefix(params.modelId, params.xhighModelIds) &&
+    !modelId.startsWith("gpt-5.6");
   const defaultLevel = isGpt56Variant ? "medium" : undefined;
   const fallbackLevels: ProviderThinkingProfile["levels"] = [
     ...OPENAI_THINKING_BASE_LEVELS,
@@ -118,6 +124,9 @@ function buildOpenAIThinkingProfile(params: {
       : []),
     ...(supportsMax ? [{ id: "max" as const }] : []),
     ...(supportsUltra ? [{ id: "ultra" as const }] : []),
+    ...(nativeCodexNeedsAccountEffortValidation
+      ? [{ id: "xhigh" as const }, { id: "max" as const }]
+      : []),
   ];
   const levels =
     agentRuntime === "codex" && resolvedCodexEfforts !== undefined
diff --git a/src/agents/model-auth-availability.test.ts b/src/agents/model-auth-availability.test.ts
index cd0eac62a4f6..3b25baadfb5d 100644
--- a/src/agents/model-auth-availability.test.ts
+++ b/src/agents/model-auth-availability.test.ts
@@ -875,6 +875,15 @@ describe("createModelAuthAvailabilityResolver", () => {
     expect(result).not.toHaveProperty("selectedRoute");
   });
 
+  it("keeps one unconfigured Codex route indeterminate until native account validation", () => {
+    expect(
+      evaluate({
+        resolution: { ...dualRoutes, routes: [subscriptionRoute] },
+        syntheticAuthProviderRefs: ["codex"],
+      }),
+    ).toMatchObject({ availability: undefined, evidence: "synthetic" });
+  });
+
   it("does not let invalid automatic profile evidence block synthetic Codex ownership", () => {
     expect(
       evaluate({
diff --git a/src/agents/model-auth-availability.ts b/src/agents/model-auth-availability.ts
index daed53540aaf..5c01163c002d 100644
--- a/src/agents/model-auth-availability.ts
+++ b/src/agents/model-auth-availability.ts
@@ -1106,6 +1106,10 @@ export function createModelAuthAvailabilityResolver(
       sourcePlan,
       configuredAuthMode: automaticRouteAuthMode,
       ...(syntheticCodexOwnsAuth ? { runtimeAuthOwner: { id: "codex" } } : {}),
+      ...(syntheticCodexOwnsAuth &&
+      resolveMergedModelProviderConfig(params.cfg, provider) === undefined
+        ? { allowNativeAuthOnSingleRoute: true }
+        : {}),
     });
     if (routeAuthDecision.kind === "deferred" && syntheticCodexOwnsAuth) {
       return { availability: undefined, routeResolution, evidence: "synthetic" };
diff --git a/src/agents/openai-model-routes.ts b/src/agents/openai-model-routes.ts
index 25ded9d10f6e..3be387b24f71 100644
--- a/src/agents/openai-model-routes.ts
+++ b/src/agents/openai-model-routes.ts
@@ -59,6 +59,7 @@ export function selectOpenAIModelRouteAuth(params: {
   sourcePlan: ProviderModelAuthSourcePlan;
   configuredAuthMode?: string;
   runtimeAuthOwner?: { id: string };
+  allowNativeAuthOnSingleRoute?: boolean;
 }) {
   return selectProviderModelRouteAuth({ provider: OPENAI_PROVIDER_ID, ...params });
 }
diff --git a/src/agents/provider-model-route-auth.test.ts b/src/agents/provider-model-route-auth.test.ts
index 90163e10d3c7..ef62b48eadfe 100644
--- a/src/agents/provider-model-route-auth.test.ts
+++ b/src/agents/provider-model-route-auth.test.ts
@@ -336,6 +336,36 @@ describe("provider model route auth", () => {
     });
   });
 
+  it("lets an explicit native owner authenticate its sole compatible route", () => {
+    expect(
+      selectProviderModelRouteAuth({
+        provider: "openai",
+        resolution: { ...routes, routes: [routes.routes[1]] },
+        runtimeAuthOwner: { id: "codex" },
+        allowNativeAuthOnSingleRoute: true,
+        sourcePlan: buildProviderModelAuthSourcePlan({ profiles: [] }),
+      }),
+    ).toEqual({
+      kind: "deferred",
+      reason: "runtime-auth-owner",
+      routeSupport: {
+        requestTransportOverrides: "none",
+        runtimePolicy: { compatibleIds: ["openclaw", "codex"] },
+      },
+    });
+  });
+
+  it("does not infer native ownership for an explicitly authored single route", () => {
+    expect(
+      selectProviderModelRouteAuth({
+        provider: "openai",
+        resolution: { ...routes, routes: [routes.routes[1]] },
+        runtimeAuthOwner: { id: "codex" },
+        sourcePlan: buildProviderModelAuthSourcePlan({ profiles: [] }),
+      }),
+    ).toMatchObject({ kind: "rejected", reason: "configured-auth" });
+  });
+
   it.each([
     ["Platform", routes.routes[0], profile("openai:chatgpt", "oauth", "ready")],
     ["subscription", routes.routes[1], profile("openai:platform", "api_key", "ready")],
diff --git a/src/agents/provider-model-route-auth.ts b/src/agents/provider-model-route-auth.ts
index 4125479207e0..e9441074e656 100644
--- a/src/agents/provider-model-route-auth.ts
+++ b/src/agents/provider-model-route-auth.ts
@@ -285,6 +285,8 @@ export function selectProviderModelRouteAuth(params: {
   configuredAuthMode?: string;
   /** Explicit native auth owner allowed to defer an otherwise unowned route. */
   runtimeAuthOwner?: { id: string };
+  /** True only when no provider transport or credentials were authored. */
+  allowNativeAuthOnSingleRoute?: boolean;
 }): ProviderModelRouteAuthDecision {
   const requiredProfile =
     params.sourcePlan.kind === "required" && params.sourcePlan.source.kind === "profile"
@@ -412,7 +414,16 @@ export function selectProviderModelRouteAuth(params: {
     const runtimeAuthOwnerIsCompatible =
       Boolean(normalizedRuntimeAuthOwner) &&
       routeSupport.runtimePolicy.compatibleIds.includes(normalizedRuntimeAuthOwner ?? "");
-    if (params.resolution.routes.length > 1 && runtimeAuthOwnerIsCompatible && !configuredRoute) {
+    const hostHasNoCredentialToHonor =
+      params.allowNativeAuthOnSingleRoute === true &&
+      params.sourcePlan.kind === "automatic" &&
+      params.sourcePlan.orderedProfiles.length === 0 &&
+      params.sourcePlan.fallback === undefined;
+    if (
+      runtimeAuthOwnerIsCompatible &&
+      !configuredRoute &&
+      (params.resolution.routes.length > 1 || hostHasNoCredentialToHonor)
+    ) {
       return { kind: "deferred", reason: "runtime-auth-owner", routeSupport };
     }
     return reject(
diff --git a/src/agents/runtime-plan/prepare-auth.ts b/src/agents/runtime-plan/prepare-auth.ts
index 37fdabe091dc..ac7f9a5ddc01 100644
--- a/src/agents/runtime-plan/prepare-auth.ts
+++ b/src/agents/runtime-plan/prepare-auth.ts
@@ -520,6 +520,9 @@ export function prepareAgentRuntimeAuth(
     sourcePlan,
     configuredAuthMode: automaticRouteAuthMode,
     ...(runtimeAuthOwner ? { runtimeAuthOwner } : {}),
+    ...(runtimeAuthOwner && configuredProvider === undefined
+      ? { allowNativeAuthOnSingleRoute: true }
+      : {}),
   });
   if (routeAuthDecision.kind === "deferred") {
     const plan = buildAgentRuntimeAuthPlan({

From 61842af8c5ce27c7dca0c01d64bebba77bde8cde Mon Sep 17 00:00:00 2001
From: Gio Della-Libera <giodl73@gmail.com>
Date: Fri, 21 Aug 2026 12:32:58 -0700
Subject: [PATCH 079/124] fix(claws): preserve unchanged owned skills on update
 (#126479)

Avoid rematerializing exact unchanged Claw-owned skills while retaining mutation and provenance blockers and failing closed if package state changes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Gio Della-Libera <giodl@microsoft.com>
Copilot-Session: 75f14ffa-b451-435e-97ce-59816458426d
---
 src/claws/lifecycle.ts                  |   4 +-
 src/claws/update-apply.packages.test.ts | 255 ++++++++++++++++++++++++
 src/claws/update-apply.ts               |  40 +++-
 3 files changed, 295 insertions(+), 4 deletions(-)
 create mode 100644 src/claws/update-apply.packages.test.ts

diff --git a/src/claws/lifecycle.ts b/src/claws/lifecycle.ts
index 9411ba601dca..09e76f5245ba 100644
--- a/src/claws/lifecycle.ts
+++ b/src/claws/lifecycle.ts
@@ -481,7 +481,7 @@ export async function buildClawAddPlan(params: {
     }
   }
 
-  for (const pkg of params.manifest.packages) {
+  for (const [index, pkg] of params.manifest.packages.entries()) {
     const preflight: ClawPackagePreflightResult = context.packagePreflight
       ? await context.packagePreflight(pkg, workspace)
       : {
@@ -493,7 +493,7 @@ export async function buildClawAddPlan(params: {
       ? undefined
       : blocker(
           preflight.code ?? "package_install_unavailable",
-          "$.packages",
+          `$.packages[${index}]`,
           preflight.message ?? "Package preflight failed.",
         );
     if (diagnostic) {
diff --git a/src/claws/update-apply.packages.test.ts b/src/claws/update-apply.packages.test.ts
new file mode 100644
index 000000000000..086bd79f6a95
--- /dev/null
+++ b/src/claws/update-apply.packages.test.ts
@@ -0,0 +1,255 @@
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { useAutoCleanupTempDirTracker } from "../../test/helpers/temp-dir.js";
+import type { PersistedClawInstall } from "./provenance.js";
+import type {
+  ClawManifest,
+  ClawOpenClawProfile,
+  ClawPackage,
+  ClawPackagePreflight,
+  ClawSourceIdentity,
+} from "./types.js";
+import { applyClawUpdatePlan } from "./update-apply.js";
+import type { ClawUpdateAction, ClawUpdatePlan } from "./update-plan.js";
+
+const tempDirs = useAutoCleanupTempDirTracker(afterEach);
+const source: ClawSourceIdentity = {
+  kind: "package",
+  name: "@acme/worker",
+  version: "2.0.0",
+  packageRoot: "/tmp/target",
+  manifestPath: "/tmp/target/openclaw.claw.json",
+  integrityKind: "artifact",
+  integrity: "sha256:target",
+  byteLength: 1,
+};
+const manifest: ClawManifest = {
+  schemaVersion: 1,
+  agent: { id: "worker", name: "Worker v2" },
+  workspace: { bootstrapFiles: {}, files: [] },
+  packages: [],
+  mcpServers: {},
+  cronJobs: [],
+};
+const install: PersistedClawInstall = {
+  schemaVersion: "openclaw.clawInstallRecord.v1",
+  claw: { ...source, version: "1.0.0", integrity: "sha256:current" },
+  manifestSchemaVersion: 1,
+  planIntegrity: "sha256:current-add-plan",
+  agentId: "worker",
+  workspace: "/tmp/workspace-worker",
+  agentConfigDigest: "sha256:current-agent",
+  agentOwnedPaths: ['agents.entries["worker"]'],
+  status: "complete",
+  addedAtMs: 1,
+  updatedAtMs: 1,
+};
+const weatherPackage: ClawPackage = {
+  kind: "skill",
+  source: "clawhub",
+  ref: "@acme/weather",
+  version: "1.0.0",
+};
+
+function plan(actions: ClawUpdateAction[]): ClawUpdatePlan {
+  return {
+    schemaVersion: "openclaw.clawUpdatePlan.v1",
+    stability: "experimental",
+    dryRun: true,
+    mutationAllowed: false,
+    planIntegrity: "sha256:update-plan",
+    found: true,
+    agentId: "worker",
+    currentClaw: { name: source.name, version: "1.0.0", integrity: "sha256:current" },
+    targetClaw: { name: source.name, version: source.version, integrity: source.integrity },
+    summary: {
+      totalActions: actions.length,
+      added: actions.filter((action) => action.action === "add").length,
+      changed: 0,
+      removed: 0,
+      released: 0,
+      unchanged: actions.filter((action) => action.action === "unchanged").length,
+      manual: 0,
+      blocked: 0,
+      capabilityChanges: 0,
+      capabilityEscalations: 0,
+    },
+    actions,
+    capabilityChanges: [],
+    readiness: { ready: true, requirements: [] },
+    blockers: [],
+    diagnostics: [],
+  };
+}
+
+function unchanged(id = "skill:@acme/weather"): ClawUpdateAction {
+  return {
+    kind: "package",
+    id,
+    action: "unchanged",
+    target: "clawhub:@acme/weather@1.0.0",
+    blocked: false,
+    reason: "Recorded package reference already matches the exact target version.",
+    currentDigest: "sha256:current-package",
+    desiredDigest: "sha256:target-package",
+  };
+}
+
+function targetSource(): ClawSourceIdentity {
+  const packageRoot = tempDirs.make("openclaw-claw-update-package-");
+  return {
+    ...source,
+    packageRoot,
+    manifestPath: join(packageRoot, "openclaw.claw.json"),
+  };
+}
+
+function options(updatePlan: ClawUpdatePlan, packagePreflight: ClawPackagePreflight) {
+  return {
+    config: {},
+    sourceMcpServers: {},
+    consentPlanIntegrity: updatePlan.planIntegrity,
+    rebuildPlan: vi.fn(async () => updatePlan),
+    readInstall: vi.fn(() => install),
+    packagePreflight,
+  };
+}
+
+describe("applyClawUpdatePlan package compatibility", () => {
+  it("does not rematerialize an unchanged Claw-owned skill during apply", async () => {
+    const updatePlan = plan([unchanged()]);
+    const applyPackage = vi.fn(async () => ({
+      appliedIds: [],
+      rollback: vi.fn(async () => undefined),
+    }));
+    const result = await applyClawUpdatePlan(
+      updatePlan,
+      {
+        targetManifest: { ...manifest, packages: [weatherPackage] },
+        targetSource: targetSource(),
+      },
+      {
+        ...options(
+          updatePlan,
+          vi.fn(async () => ({
+            ok: false,
+            code: "skill_version_conflict",
+            message: "The already installed skill cannot be added again.",
+          })),
+        ),
+        applyWorkspace: vi.fn(async () => ({
+          appliedPaths: [],
+          rollback: vi.fn(async () => undefined),
+        })),
+        applyMcp: vi.fn(async () => ({
+          appliedNames: [],
+          rollback: vi.fn(async () => undefined),
+        })),
+        applyCron: vi.fn(async () => ({
+          appliedIds: [],
+          rollback: vi.fn(async () => undefined),
+        })),
+        applyPackage,
+        persistInstall: vi.fn(() => ({ ...install, claw: source })),
+      },
+    );
+
+    expect(result.status).toBe("complete");
+    expect(result.appliedActions).toEqual([]);
+    expect(applyPackage).not.toHaveBeenCalled();
+  });
+
+  it("keeps package blockers for mutations when another package is unchanged", async () => {
+    const alertsPackage: ClawPackage = {
+      kind: "skill",
+      source: "clawhub",
+      ref: "@acme/alerts",
+      version: "1.0.0",
+    };
+    const updatePlan = plan([
+      unchanged(),
+      {
+        kind: "package",
+        id: "skill:@acme/alerts",
+        action: "add",
+        target: "clawhub:@acme/alerts@1.0.0",
+        blocked: false,
+        reason: "The target adds a skill.",
+        desiredDigest: "sha256:target-alerts",
+      },
+    ]);
+
+    await expect(
+      applyClawUpdatePlan(
+        updatePlan,
+        {
+          targetManifest: { ...manifest, packages: [weatherPackage, alertsPackage] },
+          targetSource: targetSource(),
+        },
+        options(
+          updatePlan,
+          vi.fn(async (pkg) => ({
+            ok: false,
+            code: "skill_version_conflict",
+            message: `${pkg.ref} cannot be materialized.`,
+          })),
+        ),
+      ),
+    ).rejects.toMatchObject({ code: "update_target_blocked" });
+  });
+
+  it("rejects an unchanged package that disappears after planning", async () => {
+    const updatePlan = plan([unchanged()]);
+    await expect(
+      applyClawUpdatePlan(
+        updatePlan,
+        {
+          targetManifest: { ...manifest, packages: [weatherPackage] },
+          targetSource: targetSource(),
+        },
+        options(
+          updatePlan,
+          vi.fn(async () => ({
+            ok: true,
+            action: "install" as const,
+            integrity: "sha256:resolved-package",
+            installId: "@acme/weather",
+          })),
+        ),
+      ),
+    ).rejects.toMatchObject({ code: "update_changed" });
+  });
+
+  it("keeps provenance blockers for unchanged profile extensions", async () => {
+    const targetOpenClawProfile: ClawOpenClawProfile = {
+      schemaVersion: 1,
+      agent: {},
+      extensions: [
+        {
+          id: "weather",
+          kind: "plugin",
+          format: "openclaw",
+          source: "clawhub",
+          ref: "@acme/weather",
+          version: "1.0.0",
+        },
+      ],
+    };
+    const updatePlan = plan([unchanged("plugin:@acme/weather")]);
+
+    await expect(
+      applyClawUpdatePlan(
+        updatePlan,
+        {
+          targetManifest: manifest,
+          targetOpenClawProfile,
+          targetSource: targetSource(),
+        },
+        options(
+          updatePlan,
+          vi.fn(async () => ({ ok: true, action: "reuse" as const })),
+        ),
+      ),
+    ).rejects.toMatchObject({ code: "update_target_blocked" });
+  });
+});
diff --git a/src/claws/update-apply.ts b/src/claws/update-apply.ts
index d29a49a2284b..53d901f02171 100644
--- a/src/claws/update-apply.ts
+++ b/src/claws/update-apply.ts
@@ -87,6 +87,21 @@ function comparablePlan(plan: ClawUpdatePlan): unknown {
   };
 }
 
+function unchangedPackagePaths(plan: ClawUpdatePlan, manifest: ClawManifest): Set<string> {
+  const unchangedIds = new Set(
+    plan.actions
+      .filter((action) => action.kind === "package" && action.action === "unchanged")
+      .map((action) => action.id),
+  );
+  const paths = new Set<string>();
+  manifest.packages.forEach((pkg, index) => {
+    if (unchangedIds.has(`${pkg.kind}:${pkg.ref}`)) {
+      paths.add(`$.packages[${index}]`);
+    }
+  });
+  return paths;
+}
+
 export async function applyClawUpdatePlan(
   plan: ClawUpdatePlan,
   params: {
@@ -221,9 +236,13 @@ export async function applyClawUpdatePlan(
       },
     },
   });
+  const unchangedPaths = unchangedPackagePaths(fresh, params.targetManifest);
   if (
     targetAddPlan.blockers.some(
-      (blocker) => blocker.code !== "agent_id_collision" && blocker.code !== "workspace_collision",
+      (blocker) =>
+        blocker.code !== "agent_id_collision" &&
+        blocker.code !== "workspace_collision" &&
+        !(blocker.code === "skill_version_conflict" && unchangedPaths.has(blocker.path)),
     )
   ) {
     throw new ClawUpdateMutationError(
@@ -231,10 +250,24 @@ export async function applyClawUpdatePlan(
       "The target Claw cannot be safely materialized for update.",
     );
   }
+  for (const action of fresh.actions.filter(
+    (candidate) => candidate.kind === "package" && candidate.action === "unchanged",
+  )) {
+    const addAction = targetAddPlan.actions.find(
+      (candidate) => candidate.kind === "package" && candidate.id === action.id,
+    );
+    if (!addAction || addAction.details?.expectedState === "absent") {
+      throw new ClawUpdateMutationError(
+        "update_changed",
+        `Package ${JSON.stringify(action.id)} is no longer present; build a new dry-run plan.`,
+      );
+    }
+  }
   const targetPackages = clawTargetPackages(params.targetManifest, params.targetOpenClawProfile);
   for (const action of fresh.actions.filter(
     (candidate) =>
       candidate.kind === "package" &&
+      candidate.action !== "unchanged" &&
       candidate.action !== "release" &&
       candidate.action !== "remove",
   )) {
@@ -272,7 +305,10 @@ export async function applyClawUpdatePlan(
       targetPackages.get(action.id)?.kind === "plugin",
   );
   const remainingPackageActions = fresh.actions.filter(
-    (action) => action.kind === "package" && !requirementActions.includes(action),
+    (action) =>
+      action.kind === "package" &&
+      action.action !== "unchanged" &&
+      !requirementActions.includes(action),
   );
   const applyPackageActions = async (
     actions: ClawUpdateAction[],

From b9ebfeb950b7100e064cab7a8df5f75673bb9270 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 12:33:02 -0700
Subject: [PATCH 080/124] perf(qa): isolate OTEL model-call test imports
 (#127420)

---
 .../src/service.otlp-export.test.ts           |  6 ++--
 .../runtime/otel-model-call.test-support.ts   | 33 +++++++++++++++++++
 test/e2e/qa-lab/runtime/otel-test-support.ts  | 33 -------------------
 3 files changed, 35 insertions(+), 37 deletions(-)
 create mode 100644 test/e2e/qa-lab/runtime/otel-model-call.test-support.ts

diff --git a/extensions/diagnostics-otel/src/service.otlp-export.test.ts b/extensions/diagnostics-otel/src/service.otlp-export.test.ts
index 91c6bce21ae6..b213797d1273 100644
--- a/extensions/diagnostics-otel/src/service.otlp-export.test.ts
+++ b/extensions/diagnostics-otel/src/service.otlp-export.test.ts
@@ -33,10 +33,8 @@ import {
   waitForDiagnosticEventsDrained,
 } from "openclaw/plugin-sdk/diagnostic-runtime";
 import { afterEach, beforeEach, expect, test, vi } from "vitest";
-import {
-  runModelCallAndCaptureTraceparent,
-  startLocalOtlpReceiver,
-} from "../../../test/e2e/qa-lab/runtime/otel-test-support.js";
+import { runModelCallAndCaptureTraceparent } from "../../../test/e2e/qa-lab/runtime/otel-model-call.test-support.js";
+import { startLocalOtlpReceiver } from "../../../test/e2e/qa-lab/runtime/otel-test-support.js";
 import { createDiagnosticsOtelService } from "./service.js";
 import {
   createOtelContext,
diff --git a/test/e2e/qa-lab/runtime/otel-model-call.test-support.ts b/test/e2e/qa-lab/runtime/otel-model-call.test-support.ts
new file mode 100644
index 000000000000..38d6370a907a
--- /dev/null
+++ b/test/e2e/qa-lab/runtime/otel-model-call.test-support.ts
@@ -0,0 +1,33 @@
+import type { StreamFn } from "openclaw/plugin-sdk/agent-core";
+import type { DiagnosticTraceContext } from "openclaw/plugin-sdk/diagnostic-runtime";
+import { wrapStreamFnWithDiagnosticModelCallEvents } from "../../../../src/agents/embedded-agent-runner/run/attempt.model-diagnostic-events.js";
+
+export function runModelCallAndCaptureTraceparent(params: {
+  trace: DiagnosticTraceContext;
+  runId: string;
+  callId: string;
+  provider: string;
+  model: string;
+}): string | undefined {
+  let outboundTraceparent: string | undefined;
+  const wrapped = wrapStreamFnWithDiagnosticModelCallEvents(
+    ((
+      _model: Parameters<StreamFn>[0],
+      _context: Parameters<StreamFn>[1],
+      options: Parameters<StreamFn>[2],
+    ) => {
+      outboundTraceparent = options?.headers?.traceparent;
+      return undefined as never;
+    }) as StreamFn,
+    {
+      runId: params.runId,
+      provider: params.provider,
+      model: params.model,
+      trace: params.trace,
+      nextCallId: () => params.callId,
+      suppressPluginHooks: true,
+    },
+  );
+  void wrapped({} as never, {} as never);
+  return outboundTraceparent;
+}
diff --git a/test/e2e/qa-lab/runtime/otel-test-support.ts b/test/e2e/qa-lab/runtime/otel-test-support.ts
index 4bc834a1e713..f20edb2838d2 100644
--- a/test/e2e/qa-lab/runtime/otel-test-support.ts
+++ b/test/e2e/qa-lab/runtime/otel-test-support.ts
@@ -1,9 +1,6 @@
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
 import { Socket } from "node:net";
 import { gunzipSync } from "node:zlib";
-import type { StreamFn } from "openclaw/plugin-sdk/agent-core";
-import type { DiagnosticTraceContext } from "openclaw/plugin-sdk/diagnostic-runtime";
-import { wrapStreamFnWithDiagnosticModelCallEvents } from "../../../../src/agents/embedded-agent-runner/run/attempt.model-diagnostic-events.js";
 
 export type OtlpSignal = "logs" | "metrics" | "traces";
 
@@ -116,36 +113,6 @@ export function createRecentTraceSummary() {
   };
 }
 
-export function runModelCallAndCaptureTraceparent(params: {
-  trace: DiagnosticTraceContext;
-  runId: string;
-  callId: string;
-  provider: string;
-  model: string;
-}): string | undefined {
-  let outboundTraceparent: string | undefined;
-  const wrapped = wrapStreamFnWithDiagnosticModelCallEvents(
-    ((
-      _model: Parameters<StreamFn>[0],
-      _context: Parameters<StreamFn>[1],
-      options: Parameters<StreamFn>[2],
-    ) => {
-      outboundTraceparent = options?.headers?.traceparent;
-      return undefined as never;
-    }) as StreamFn,
-    {
-      runId: params.runId,
-      provider: params.provider,
-      model: params.model,
-      trace: params.trace,
-      nextCallId: () => params.callId,
-      suppressPluginHooks: true,
-    },
-  );
-  void wrapped({} as never, {} as never);
-  return outboundTraceparent;
-}
-
 const OTLP_SIGNAL_PATHS = new Map<string, OtlpSignal>([
   ["/v1/traces", "traces"],
   ["/v1/metrics", "metrics"],

From 3376c29800166a3151cbca6b8ab204964e97ac39 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 12:42:14 -0700
Subject: [PATCH 081/124] perf(discord): avoid redundant payload cleaning
 (#127422)

Co-authored-by: Amp <amp@ampcode.com>
---
 extensions/discord/src/send.components.ts      | 10 +++-------
 extensions/discord/src/send.message-request.ts | 11 +++++------
 2 files changed, 8 insertions(+), 13 deletions(-)

diff --git a/extensions/discord/src/send.components.ts b/extensions/discord/src/send.components.ts
index 83ac25d54c7e..445af5f91c07 100644
--- a/extensions/discord/src/send.components.ts
+++ b/extensions/discord/src/send.components.ts
@@ -34,7 +34,6 @@ import {
   createDiscordMessageNonce,
   resolveChannelId,
   resolveDiscordChannel,
-  stripUndefinedFields,
   SUPPRESS_NOTIFICATIONS_FLAG,
   type DiscordAllowedMentions,
 } from "./send.shared.js";
@@ -201,10 +200,7 @@ async function buildDiscordComponentPayload(params: {
   spec: DiscordComponentMessageSpec;
   opts: DiscordComponentSendOpts;
   accountId: string;
-}): Promise<{
-  body: ReturnType<typeof stripUndefinedFields>;
-  buildResult: ReturnType<typeof buildDiscordComponentMessage>;
-}> {
+}) {
   const messageReference = params.opts.reply
     ? { message_id: params.opts.reply.messageId, fail_if_not_exists: false }
     : undefined;
@@ -260,10 +256,10 @@ async function buildDiscordComponentPayload(params: {
     ...(finalFlags ? { flags: finalFlags } : {}),
     ...(files ? { files } : {}),
   };
-  const body = stripUndefinedFields({
+  const body = {
     ...serializePayload(payload),
     ...(messageReference ? { message_reference: messageReference } : {}),
-  });
+  };
 
   return { body, buildResult };
 }
diff --git a/extensions/discord/src/send.message-request.ts b/extensions/discord/src/send.message-request.ts
index 6db1dccb80be..513db7ed69a0 100644
--- a/extensions/discord/src/send.message-request.ts
+++ b/extensions/discord/src/send.message-request.ts
@@ -8,9 +8,8 @@ import {
   type MessagePayloadObject,
   type TopLevelComponents,
 } from "./internal/discord.js";
-import { stripUndefinedFields } from "./internal/undefined-fields.js";
 
-export { stripUndefinedFields };
+export { stripUndefinedFields } from "./internal/undefined-fields.js";
 
 const SUPPRESS_EMBEDS_FLAG = MessageFlags.SuppressEmbeds;
 export const SUPPRESS_NOTIFICATIONS_FLAG = MessageFlags.SuppressNotifications;
@@ -123,14 +122,14 @@ export function buildDiscordMessageRequest(params: DiscordMessageRequestParams)
     params.endpoint === "create-message"
       ? (params.nonce ?? createDiscordMessageNonce())
       : undefined;
-  return stripUndefinedFields({
+  return {
     ...serializePayload(payload),
     ...(params.replyTo
       ? { message_reference: { message_id: params.replyTo, fail_if_not_exists: false } }
       : {}),
-    nonce,
-    enforce_nonce: nonce ? true : undefined,
-  });
+    ...(nonce !== undefined ? { nonce } : {}),
+    ...(nonce ? { enforce_nonce: true } : {}),
+  };
 }
 
 function hasV2Components(components?: TopLevelComponents[]): boolean {

From bc1f9609a3a217805163b40c135b338cee8708aa Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 12:48:24 -0700
Subject: [PATCH 082/124] fix(status): surface an invalid config instead of
 reporting a healthy system (#127402)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

openclaw status exited 0 with a complete, healthy-looking report when the
config file failed validation, silently substituting defaults for the
operator's authored values. Every sibling command — config validate,
agents list, models list, doctor — reported the failure.

readBestEffortConfigSnapshotFromContext already read snapshot.valid and
dropped it, and BestEffortConfigSnapshot had nowhere to carry it, so no
consumer of the best-effort path could report it. Carry the fact from its
producer as configDiagnostics and render it in text, --json, and --all.

The sibling readSourceConfigBestEffortFromContext already states the rule
seventeen lines below: best-effort legitimizes the fallback value, not the
silence.
---
 src/commands/status-all/report-data.ts        |  1 +
 src/commands/status-all/report-lines.test.ts  | 13 +++-
 src/commands/status-all/report-lines.ts       | 10 +++
 src/commands/status-json-payload.test.ts      | 68 +++++++++-------
 src/commands/status-json-payload.ts           |  3 +
 src/commands/status-json-runtime.ts           |  1 +
 src/commands/status.command.text-runtime.ts   |  1 +
 src/commands/status.command.ts                | 11 +++
 src/commands/status.format.ts                 | 14 ++++
 src/commands/status.scan-execute.test.ts      |  5 ++
 src/commands/status.scan-execute.ts           |  1 +
 src/commands/status.scan-overview.test.ts     |  1 +
 src/commands/status.scan-overview.ts          |  4 +
 src/commands/status.scan-result.test.ts       |  2 +
 .../status.scan.config-shared.test.ts         | 34 +++++++-
 src/commands/status.scan.config-shared.ts     | 10 +--
 src/commands/status.scan.fast-json.test.ts    | 22 ++++++
 src/commands/status.scan.test-helpers.ts      | 17 ++--
 src/commands/status.test-support.ts           |  1 +
 src/commands/status.test.ts                   | 78 ++++++++++++++++++-
 src/config/io.best-effort.test.ts             | 21 +++++
 src/config/io.snapshot.ts                     | 10 ++-
 src/config/io.types.ts                        |  3 +-
 23 files changed, 283 insertions(+), 48 deletions(-)

diff --git a/src/commands/status-all/report-data.ts b/src/commands/status-all/report-data.ts
index 374c06e8b197..f6daa11bc5e0 100644
--- a/src/commands/status-all/report-data.ts
+++ b/src/commands/status-all/report-data.ts
@@ -234,6 +234,7 @@ export async function buildStatusAllReportData(params: {
   });
 
   return {
+    configDiagnostics: params.overview.configDiagnostics,
     overviewRows,
     channels: params.overview.channels,
     channelIssues: params.overview.channelIssues.map((issue) => ({
diff --git a/src/commands/status-all/report-lines.test.ts b/src/commands/status-all/report-lines.test.ts
index 665b3967caea..b3aace36cb4d 100644
--- a/src/commands/status-all/report-lines.test.ts
+++ b/src/commands/status-all/report-lines.test.ts
@@ -10,7 +10,7 @@ vi.mock("./diagnosis.js", () => ({
 }));
 
 describe("buildStatusAllReportLines", () => {
-  it("renders bootstrap column using file-presence semantics", async () => {
+  it("renders bootstrap state and invalid config diagnostics", async () => {
     const progress: ProgressReporter = {
       setLabel: () => {},
       setPercent: () => {},
@@ -19,6 +19,10 @@ describe("buildStatusAllReportLines", () => {
     };
     const lines = await buildStatusAllReportLines({
       progress,
+      configDiagnostics: {
+        path: "/tmp/openclaw.json",
+        issues: [{ path: "gateway.port", message: "invalid" }],
+      },
       overviewRows: [{ Item: "Gateway", Value: "ok" }],
       channels: {
         rows: [
@@ -84,6 +88,13 @@ describe("buildStatusAllReportLines", () => {
     expect(output).toContain("Bootstrap file");
     expect(output).toContain("PRESENT");
     expect(output).toContain("ABSENT");
+    expect(output).toContain("Config diagnostics:");
+    expect(output).toContain("Config file is invalid: /tmp/openclaw.json");
+    expect(output).toContain("gateway.port: invalid");
+    expect(output).toContain("Fix: openclaw doctor --fix");
+    expect(output.indexOf("Config diagnostics:")).toBeLessThan(
+      output.indexOf("OpenClaw status --all"),
+    );
     expect(output).not.toContain(String.fromCharCode(0xd83d));
     expect(diagnosisSpy).toHaveBeenCalledOnce();
     const [diagnosisOptions] = diagnosisSpy.mock.calls[0] as unknown as [
diff --git a/src/commands/status-all/report-lines.ts b/src/commands/status-all/report-lines.ts
index 4076bb8290fd..b90d8325d072 100644
--- a/src/commands/status-all/report-lines.ts
+++ b/src/commands/status-all/report-lines.ts
@@ -5,6 +5,8 @@ import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
 import { getTerminalTableWidth, renderTable } from "../../../packages/terminal-core/src/table.js";
 import { isRich, theme } from "../../../packages/terminal-core/src/theme.js";
 import type { ProgressReporter } from "../../cli/progress.js";
+import type { BestEffortConfigSnapshot } from "../../config/io.js";
+import { formatStatusConfigDiagnosticEntries } from "../status.format.js";
 import { buildStatusChannelsTableRows, statusChannelsTableColumns } from "./channels-table.js";
 import { appendStatusAllDiagnosis } from "./diagnosis.js";
 import {
@@ -51,6 +53,7 @@ type AgentStatusLike = {
 /** Builds the complete status-all text report, including overview tables and diagnosis lines. */
 export async function buildStatusAllReportLines(params: {
   progress: ProgressReporter;
+  configDiagnostics: BestEffortConfigSnapshot["configDiagnostics"];
   overviewRows: OverviewRow[];
   channels: ChannelsTable;
   channelIssues: ChannelIssueLike[];
@@ -71,6 +74,13 @@ export async function buildStatusAllReportLines(params: {
   const tableWidth = getTerminalTableWidth();
 
   const lines: string[] = [];
+  if (params.configDiagnostics) {
+    lines.push(
+      warn("Config diagnostics:"),
+      ...formatStatusConfigDiagnosticEntries(params.configDiagnostics),
+      "",
+    );
+  }
   lines.push(heading("OpenClaw status --all"));
   appendStatusReportSections({
     lines,
diff --git a/src/commands/status-json-payload.test.ts b/src/commands/status-json-payload.test.ts
index a02777cc2cd8..f335c0bba72c 100644
--- a/src/commands/status-json-payload.test.ts
+++ b/src/commands/status-json-payload.test.ts
@@ -78,6 +78,10 @@ describe("status-json-payload", () => {
         memory: null,
         memoryPlugin: { enabled: true },
         agents: [{ id: "main" }],
+        configDiagnostics: {
+          path: "/tmp/openclaw.json",
+          issues: [{ path: "gateway.port", message: "invalid" }],
+        },
         secretDiagnostics: ["diag"],
         securityAudit: { summary: { critical: 1 } },
         health: { ok: true },
@@ -119,6 +123,10 @@ describe("status-json-payload", () => {
       gatewayService: { label: "LaunchAgent", installed: true, loadedText: "loaded" },
       nodeService: { label: "node", installed: true, loadedText: "loaded" },
       agents: [{ id: "main" }],
+      configDiagnostics: {
+        path: "/tmp/openclaw.json",
+        issues: [{ path: "gateway.port", message: "invalid" }],
+      },
       secretDiagnostics: ["diag"],
       securityAudit: { summary: { critical: 1 } },
       health: { ok: true },
@@ -138,34 +146,36 @@ describe("status-json-payload", () => {
     });
   });
   it("omits optional sections when they are absent", () => {
-    expect(
-      buildStatusJsonPayload({
-        summary: { ok: true },
-        surface: {
-          cfg: { gateway: {} },
-          update: {
-            root: "/tmp/openclaw",
-            installKind: "package",
-            packageManager: "npm",
-          } as never,
-          tailscaleMode: "off",
-          gatewayMode: "local",
-          remoteUrlMissing: false,
-          gatewayConnection: { url: "ws://127.0.0.1:18789" },
-          gatewayReachable: false,
-          gatewayProbe: null,
-          gatewayProbeAuth: null,
-          gatewaySelf: null,
-          gatewayProbeAuthWarning: null,
-          gatewayService: { label: "LaunchAgent", installed: false, loadedText: "not installed" },
-          nodeService: { label: "node", installed: false, loadedText: "not installed" },
-        },
-        osSummary: { platform: "linux" },
-        memory: null,
-        memoryPlugin: null,
-        agents: [],
-        secretDiagnostics: [],
-      }),
-    ).not.toHaveProperty("securityAudit");
+    const payload = buildStatusJsonPayload({
+      summary: { ok: true },
+      surface: {
+        cfg: { gateway: {} },
+        update: {
+          root: "/tmp/openclaw",
+          installKind: "package",
+          packageManager: "npm",
+        } as never,
+        tailscaleMode: "off",
+        gatewayMode: "local",
+        remoteUrlMissing: false,
+        gatewayConnection: { url: "ws://127.0.0.1:18789" },
+        gatewayReachable: false,
+        gatewayProbe: null,
+        gatewayProbeAuth: null,
+        gatewaySelf: null,
+        gatewayProbeAuthWarning: null,
+        gatewayService: { label: "LaunchAgent", installed: false, loadedText: "not installed" },
+        nodeService: { label: "node", installed: false, loadedText: "not installed" },
+      },
+      osSummary: { platform: "linux" },
+      memory: null,
+      memoryPlugin: null,
+      agents: [],
+      configDiagnostics: null,
+      secretDiagnostics: [],
+    });
+
+    expect(payload).not.toHaveProperty("configDiagnostics");
+    expect(payload).not.toHaveProperty("securityAudit");
   });
 });
diff --git a/src/commands/status-json-payload.ts b/src/commands/status-json-payload.ts
index 3015f82a460e..48e0b245403a 100644
--- a/src/commands/status-json-payload.ts
+++ b/src/commands/status-json-payload.ts
@@ -1,6 +1,7 @@
 // Builds the stable JSON payload for `openclaw status --json`.
 // Optional deep fields are included only when their upstream probes actually ran.
 
+import type { BestEffortConfigSnapshot } from "../config/io.js";
 import { resolveStatusUpdateChannelInfo } from "./status-all/format.js";
 import {
   buildStatusGatewayJsonPayloadFromSurface,
@@ -15,6 +16,7 @@ export function buildStatusJsonPayload(params: {
   memory: unknown;
   memoryPlugin: unknown;
   agents: unknown;
+  configDiagnostics: BestEffortConfigSnapshot["configDiagnostics"];
   secretDiagnostics: string[];
   securityAudit?: unknown;
   health?: unknown;
@@ -38,6 +40,7 @@ export function buildStatusJsonPayload(params: {
     gatewayService: params.surface.gatewayService,
     nodeService: params.surface.nodeService,
     agents: params.agents,
+    ...(params.configDiagnostics ? { configDiagnostics: params.configDiagnostics } : {}),
     secretDiagnostics: params.secretDiagnostics,
     ...(params.securityAudit ? { securityAudit: params.securityAudit } : {}),
     ...(params.pluginCompatibility
diff --git a/src/commands/status-json-runtime.ts b/src/commands/status-json-runtime.ts
index 569720a7b871..31e5af241dff 100644
--- a/src/commands/status-json-runtime.ts
+++ b/src/commands/status-json-runtime.ts
@@ -45,6 +45,7 @@ export async function resolveStatusJsonOutput(params: {
     memory: scan.memory,
     memoryPlugin: scan.memoryPlugin,
     agents: scan.agentStatus,
+    configDiagnostics: scan.configDiagnostics,
     secretDiagnostics: scan.secretDiagnostics,
     securityAudit,
     health,
diff --git a/src/commands/status.command.text-runtime.ts b/src/commands/status.command.text-runtime.ts
index 0a70ffac2c4c..df0d11c0f5d9 100644
--- a/src/commands/status.command.text-runtime.ts
+++ b/src/commands/status.command.text-runtime.ts
@@ -40,6 +40,7 @@ export {
   formatDuration,
   formatKTokens,
   formatPromptCacheCompact,
+  formatStatusConfigDiagnosticEntries,
   formatTokensCompact,
   shortenText,
 } from "./status.format.js";
diff --git a/src/commands/status.command.ts b/src/commands/status.command.ts
index 83497cbff77f..d0637de942d2 100644
--- a/src/commands/status.command.ts
+++ b/src/commands/status.command.ts
@@ -163,6 +163,7 @@ export async function statusCommand(
     agentStatus,
     channels,
     summary,
+    configDiagnostics,
     secretDiagnostics,
     memory,
     memoryPlugin,
@@ -170,6 +171,16 @@ export async function statusCommand(
     env,
   } = scan;
 
+  if (configDiagnostics) {
+    const { formatStatusConfigDiagnosticEntries, theme } =
+      await statusCommandTextRuntimeLoader.load();
+    runtime.log(theme.warn("Config diagnostics:"));
+    for (const entry of formatStatusConfigDiagnosticEntries(configDiagnostics)) {
+      runtime.log(entry);
+    }
+    runtime.log("");
+  }
+
   const {
     securityAudit,
     usage,
diff --git a/src/commands/status.format.ts b/src/commands/status.format.ts
index 64ec61b8b8da..eb38d5035539 100644
--- a/src/commands/status.format.ts
+++ b/src/commands/status.format.ts
@@ -2,6 +2,9 @@
 // These helpers are shared by report rows and command output surfaces.
 
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
+import { sanitizeTerminalText } from "../../packages/terminal-core/src/safe-text.js";
+import type { BestEffortConfigSnapshot } from "../config/io.js";
+import { formatConfigIssueLines } from "../config/issue-format.js";
 import { getSystemdCgroupHygieneSummary } from "../daemon/service-runtime.js";
 import { formatDurationPrecise } from "../infra/format-time/format-duration.ts";
 import { formatRuntimeStatusWithDetails } from "../infra/runtime-status.ts";
@@ -11,6 +14,17 @@ export { shortenText } from "./text-format.js";
 
 export const formatKTokens = formatTokenCount;
 
+/** Formats the actionable entries shown under status config diagnostic headings. */
+export function formatStatusConfigDiagnosticEntries(
+  diagnostics: NonNullable<BestEffortConfigSnapshot["configDiagnostics"]>,
+): string[] {
+  return [
+    `- Config file is invalid: ${sanitizeTerminalText(diagnostics.path)}`,
+    ...formatConfigIssueLines(diagnostics.issues, "-", { normalizeRoot: true }),
+    "- Fix: openclaw doctor --fix",
+  ];
+}
+
 /** Formats a duration or returns `unknown` for missing/non-finite values. */
 export const formatDuration = (ms: number | null | undefined) => {
   if (ms == null || !Number.isFinite(ms)) {
diff --git a/src/commands/status.scan-execute.test.ts b/src/commands/status.scan-execute.test.ts
index 45743002aac6..a83ae27d5b36 100644
--- a/src/commands/status.scan-execute.test.ts
+++ b/src/commands/status.scan-execute.test.ts
@@ -30,6 +30,10 @@ describe("executeStatusScanFromOverview", () => {
     const overview = {
       cfg: { channels: {} },
       sourceConfig: { channels: {} },
+      configDiagnostics: {
+        path: "/tmp/openclaw.json",
+        issues: [{ path: "gateway.port", message: "invalid" }],
+      },
       secretDiagnostics: ["diag"],
       osSummary: { label: "linux" },
       tailscaleMode: "tailnet",
@@ -81,6 +85,7 @@ describe("executeStatusScanFromOverview", () => {
     });
     expect(result.cfg).toBe(overview.cfg);
     expect(result.sourceConfig).toBe(overview.sourceConfig);
+    expect(result.configDiagnostics).toBe(overview.configDiagnostics);
     expect(result.secretDiagnostics).toEqual(["diag"]);
     expect(result.tailscaleDns).toBe("box.tail.ts.net");
     expect(result.tailscaleHttpsUrl).toBe("https://box.tail.ts.net");
diff --git a/src/commands/status.scan-execute.ts b/src/commands/status.scan-execute.ts
index 5d093925b0ba..ff8f85b7df1a 100644
--- a/src/commands/status.scan-execute.ts
+++ b/src/commands/status.scan-execute.ts
@@ -42,6 +42,7 @@ export async function executeStatusScanFromOverview(params: {
     env: params.overview.env ?? {},
     cfg: params.overview.cfg,
     sourceConfig: params.overview.sourceConfig,
+    configDiagnostics: params.overview.configDiagnostics,
     secretDiagnostics: params.overview.secretDiagnostics,
     osSummary: params.overview.osSummary,
     tailscaleMode: params.overview.tailscaleMode,
diff --git a/src/commands/status.scan-overview.test.ts b/src/commands/status.scan-overview.test.ts
index b8a81c2adc6c..b28f240267b2 100644
--- a/src/commands/status.scan-overview.test.ts
+++ b/src/commands/status.scan-overview.test.ts
@@ -93,6 +93,7 @@ describe("collectStatusScanOverview", () => {
     mocks.readBestEffortConfigSnapshot.mockResolvedValue({
       config: { session: {} },
       sourceConfig: { session: { raw: true } },
+      configDiagnostics: null,
     });
     mocks.resolveCommandConfigWithSecrets.mockResolvedValue({
       resolvedConfig: { session: {} },
diff --git a/src/commands/status.scan-overview.ts b/src/commands/status.scan-overview.ts
index afbf5837eb0e..032c80493da2 100644
--- a/src/commands/status.scan-overview.ts
+++ b/src/commands/status.scan-overview.ts
@@ -1,6 +1,7 @@
 // Shared status scan overview used by compact status, status --json, and status --all.
 // It collects config, update, gateway, channel, and local agent state before specialized callers add details.
 
+import type { BestEffortConfigSnapshot } from "../config/io.js";
 import type { OpenClawConfig } from "../config/types.js";
 import type { collectChannelStatusIssues as collectChannelStatusIssuesFn } from "../infra/channels-status-issues.js";
 import { resolveOsSummary } from "../infra/os-summary.js";
@@ -76,6 +77,7 @@ export type StatusScanOverviewResult = {
   skipColdStartNetworkChecks: boolean;
   cfg: OpenClawConfig;
   sourceConfig: OpenClawConfig;
+  configDiagnostics: BestEffortConfigSnapshot["configDiagnostics"];
   secretDiagnostics: string[];
   osSummary: ReturnType<typeof resolveOsSummary>;
   tailscaleMode: string;
@@ -149,6 +151,7 @@ export async function collectStatusScanOverview(params: {
     coldStart,
     sourceConfig,
     resolvedConfig: cfg,
+    configDiagnostics,
     secretDiagnostics,
   } = await loadStatusScanCommandConfig({
     env,
@@ -326,6 +329,7 @@ export async function collectStatusScanOverview(params: {
     skipColdStartNetworkChecks: bootstrap.skipColdStartNetworkChecks,
     cfg,
     sourceConfig,
+    configDiagnostics,
     secretDiagnostics,
     osSummary,
     tailscaleMode: bootstrap.tailscaleMode,
diff --git a/src/commands/status.scan-result.test.ts b/src/commands/status.scan-result.test.ts
index 12acb88a4d28..fe8d17cb73a4 100644
--- a/src/commands/status.scan-result.test.ts
+++ b/src/commands/status.scan-result.test.ts
@@ -100,6 +100,7 @@ describe("buildStatusScanResult", () => {
       buildStatusScanResult({
         cfg: { gateway: {} },
         sourceConfig: { gateway: {} },
+        configDiagnostics: null,
         secretDiagnostics: ["diag"],
         osSummary,
         tailscaleMode: "serve",
@@ -118,6 +119,7 @@ describe("buildStatusScanResult", () => {
     ).toEqual({
       cfg: { gateway: {} },
       sourceConfig: { gateway: {} },
+      configDiagnostics: null,
       secretDiagnostics: ["diag"],
       osSummary,
       tailscaleMode: "serve",
diff --git a/src/commands/status.scan.config-shared.test.ts b/src/commands/status.scan.config-shared.test.ts
index 0ec8d908b228..2e64e54e1021 100644
--- a/src/commands/status.scan.config-shared.test.ts
+++ b/src/commands/status.scan.config-shared.test.ts
@@ -23,6 +23,7 @@ describe("status.scan.config-shared", () => {
     const readConfigSnapshot = vi.fn(async () => ({
       config: { channels: { quietchat: {} } },
       sourceConfig: { channels: { quietchat: {} } },
+      configDiagnostics: null,
     }));
     const resolveConfig = vi.fn(async () => ({
       resolvedConfig: { channels: { quietchat: {} } },
@@ -43,6 +44,7 @@ describe("status.scan.config-shared", () => {
       coldStart: true,
       sourceConfig: {},
       resolvedConfig: {},
+      configDiagnostics: null,
       secretDiagnostics: [],
     });
   });
@@ -53,6 +55,7 @@ describe("status.scan.config-shared", () => {
     const readConfigSnapshot = vi.fn(async () => ({
       config: sourceConfig,
       sourceConfig,
+      configDiagnostics: null,
     }));
     const resolveConfig = vi.fn(async () => ({
       resolvedConfig,
@@ -73,6 +76,7 @@ describe("status.scan.config-shared", () => {
       coldStart: false,
       sourceConfig,
       resolvedConfig,
+      configDiagnostics: null,
       secretDiagnostics: ["resolved"],
     });
   });
@@ -103,7 +107,11 @@ describe("status.scan.config-shared", () => {
 
     const result = await loadStatusScanCommandConfig({
       commandName: "status",
-      readConfigSnapshot: async () => ({ config: loadedConfig, sourceConfig }),
+      readConfigSnapshot: async () => ({
+        config: loadedConfig,
+        sourceConfig,
+        configDiagnostics: null,
+      }),
       resolveConfig,
       env: { VITEST: "true" },
     });
@@ -113,12 +121,33 @@ describe("status.scan.config-shared", () => {
     expect(result.resolvedConfig).toBe(resolvedConfig);
   });
 
+  it("carries invalid config diagnostics alongside the best-effort config", async () => {
+    const configDiagnostics = {
+      path: "/tmp/openclaw.json",
+      issues: [{ path: "gateway.port", message: "invalid" }],
+    };
+
+    const result = await loadStatusScanCommandConfig({
+      commandName: "status",
+      readConfigSnapshot: async () => ({
+        config: {},
+        sourceConfig: {},
+        configDiagnostics,
+      }),
+      resolveConfig: async () => ({ resolvedConfig: {}, diagnostics: [] }),
+      env: { VITEST: "true" },
+    });
+
+    expect(result.configDiagnostics).toBe(configDiagnostics);
+  });
+
   it("adds a status diagnostic for gateway token source conflicts", async () => {
     const sourceConfig = { gateway: { auth: { token: "config-token" } } };
     const resolvedConfig = sourceConfig;
     const readConfigSnapshot = vi.fn(async () => ({
       config: sourceConfig,
       sourceConfig,
+      configDiagnostics: null,
     }));
     const resolveConfig = vi.fn(async () => ({
       resolvedConfig,
@@ -143,6 +172,7 @@ describe("status.scan.config-shared", () => {
     const readConfigSnapshot = vi.fn(async () => ({
       config: sourceConfig,
       sourceConfig,
+      configDiagnostics: null,
     }));
     const resolveConfig = vi.fn(async () => ({
       resolvedConfig: sourceConfig,
@@ -172,6 +202,7 @@ describe("status.scan.config-shared", () => {
     const readConfigSnapshot = vi.fn(async () => ({
       config: sourceConfig,
       sourceConfig,
+      configDiagnostics: null,
     }));
     const resolveConfig = vi.fn(async () => ({
       resolvedConfig: sourceConfig,
@@ -200,6 +231,7 @@ describe("status.scan.config-shared", () => {
     const readConfigSnapshot = vi.fn(async () => ({
       config: sourceConfig,
       sourceConfig,
+      configDiagnostics: null,
     }));
     const resolveConfig = vi.fn(async () => ({
       resolvedConfig: sourceConfig,
diff --git a/src/commands/status.scan.config-shared.ts b/src/commands/status.scan.config-shared.ts
index caab70eb83f9..f1274913db98 100644
--- a/src/commands/status.scan.config-shared.ts
+++ b/src/commands/status.scan.config-shared.ts
@@ -2,6 +2,7 @@
 // Handles missing-config cold start and secret diagnostics before scan work begins.
 
 import { existsSync } from "node:fs";
+import type { BestEffortConfigSnapshot } from "../config/io.js";
 import { resolveConfigPath } from "../config/paths.js";
 import type { OpenClawConfig } from "../config/types.js";
 import { resolveGatewayAuthTokenSourceConflict } from "../gateway/auth-token-source-conflict.js";
@@ -25,10 +26,7 @@ function resolveStatusScanColdStart(params?: {
 /** Loads best-effort config, resolves read-only secrets, and appends status secret diagnostics. */
 export async function loadStatusScanCommandConfig(params: {
   commandName: string;
-  readConfigSnapshot: () => Promise<{
-    config: OpenClawConfig;
-    sourceConfig: OpenClawConfig;
-  }>;
+  readConfigSnapshot: () => Promise<BestEffortConfigSnapshot>;
   resolveConfig: (
     sourceConfig: OpenClawConfig,
   ) => Promise<{ resolvedConfig: OpenClawConfig; diagnostics: string[] }>;
@@ -38,6 +36,7 @@ export async function loadStatusScanCommandConfig(params: {
   coldStart: boolean;
   sourceConfig: OpenClawConfig;
   resolvedConfig: OpenClawConfig;
+  configDiagnostics: BestEffortConfigSnapshot["configDiagnostics"];
   secretDiagnostics: string[];
 }> {
   const env = params.env ?? process.env;
@@ -47,7 +46,7 @@ export async function loadStatusScanCommandConfig(params: {
   });
   const configSnapshot =
     coldStart && params.allowMissingConfigFastPath === true
-      ? { config: {}, sourceConfig: {} }
+      ? { config: {}, sourceConfig: {}, configDiagnostics: null }
       : await params.readConfigSnapshot();
   const loadedConfig = configSnapshot.config;
   const sourceConfig = configSnapshot.sourceConfig;
@@ -61,6 +60,7 @@ export async function loadStatusScanCommandConfig(params: {
     coldStart,
     sourceConfig,
     resolvedConfig,
+    configDiagnostics: configSnapshot.configDiagnostics,
     secretDiagnostics: tokenConflict ? [...diagnostics, tokenConflict.diagnostic] : diagnostics,
   };
 }
diff --git a/src/commands/status.scan.fast-json.test.ts b/src/commands/status.scan.fast-json.test.ts
index 25e40a09de62..d695ca6a97ea 100644
--- a/src/commands/status.scan.fast-json.test.ts
+++ b/src/commands/status.scan.fast-json.test.ts
@@ -96,6 +96,28 @@ describe("scanStatusJsonFast", () => {
     expect(loggingStateRef.forceConsoleToStderr).toBe(false);
   });
 
+  it("carries invalid config diagnostics through the lean JSON scan", async () => {
+    const config = createStatusMemorySearchConfig();
+    const configDiagnostics = {
+      path: "/tmp/openclaw.json",
+      issues: [
+        {
+          path: "gateway.port",
+          message: "Invalid input: expected number, received string",
+        },
+      ],
+    };
+    mocks.readBestEffortConfigSnapshot.mockResolvedValue({
+      config,
+      sourceConfig: config,
+      configDiagnostics,
+    });
+
+    const result = await scanStatusJsonFast({}, {} as never);
+
+    expect(result.configDiagnostics).toEqual(configDiagnostics);
+  });
+
   it("keeps resolved and source channel configs available without loading runtime plugins", async () => {
     mocks.hasConfiguredChannels.mockReturnValue(true);
     applyStatusScanDefaults(mocks, {
diff --git a/src/commands/status.scan.test-helpers.ts b/src/commands/status.scan.test-helpers.ts
index 6426b0646696..138f3d177db8 100644
--- a/src/commands/status.scan.test-helpers.ts
+++ b/src/commands/status.scan.test-helpers.ts
@@ -13,6 +13,7 @@ type StatusScanSharedMocks = {
   hasConfiguredChannels: UnknownMock;
   hasConfiguredChannelsForReadOnlyScope: UnknownMock;
   readBestEffortConfig: UnknownMock;
+  readBestEffortConfigSnapshot: UnknownMock;
   resolveCommandSecretRefsViaGateway: UnknownMock;
   getUpdateCheckResult: UnknownMock;
   getAgentLocalStatuses: UnknownMock;
@@ -33,6 +34,7 @@ export function createStatusScanSharedMocks(configPathLabel: string): StatusScan
     hasConfiguredChannels: vi.fn(),
     hasConfiguredChannelsForReadOnlyScope: vi.fn(),
     readBestEffortConfig: vi.fn(),
+    readBestEffortConfigSnapshot: vi.fn(),
     resolveCommandSecretRefsViaGateway: vi.fn(),
     getUpdateCheckResult: vi.fn(),
     getAgentLocalStatuses: vi.fn(),
@@ -208,17 +210,11 @@ export async function loadStatusScanModuleForTest(
 
   vi.doMock("../config/io.js", () => ({
     readBestEffortConfig: mocks.readBestEffortConfig,
-    readBestEffortConfigSnapshot: async () => {
-      const config = await mocks.readBestEffortConfig();
-      return { config, sourceConfig: config };
-    },
+    readBestEffortConfigSnapshot: mocks.readBestEffortConfigSnapshot,
   }));
   vi.doMock("../config/config.js", () => ({
     readBestEffortConfig: mocks.readBestEffortConfig,
-    readBestEffortConfigSnapshot: async () => {
-      const config = await mocks.readBestEffortConfig();
-      return { config, sourceConfig: config };
-    },
+    readBestEffortConfigSnapshot: mocks.readBestEffortConfigSnapshot,
     resolveGatewayPort: mocks.resolveGatewayPort,
   }));
   vi.doMock("../cli/command-secret-targets.js", () => ({
@@ -424,6 +420,11 @@ export function applyStatusScanDefaults(
     );
   });
   mocks.readBestEffortConfig.mockResolvedValue(sourceConfig);
+  mocks.readBestEffortConfigSnapshot.mockResolvedValue({
+    config: sourceConfig,
+    sourceConfig,
+    configDiagnostics: null,
+  });
   mocks.resolveCommandSecretRefsViaGateway.mockResolvedValue({
     resolvedConfig,
     diagnostics: [],
diff --git a/src/commands/status.test-support.ts b/src/commands/status.test-support.ts
index 675bb58603ae..c49c60bcabaa 100644
--- a/src/commands/status.test-support.ts
+++ b/src/commands/status.test-support.ts
@@ -172,6 +172,7 @@ export function createStatusScanResultFixture(
     env: { OPENCLAW_STATE_DIR: STATUS_TEST_STATE_DIR },
     cfg: baseStatusCfg,
     sourceConfig: baseStatusCfg,
+    configDiagnostics: null,
     secretDiagnostics: [],
     osSummary: {
       platform: "linux",
diff --git a/src/commands/status.test.ts b/src/commands/status.test.ts
index 25246fedc165..67822d0d0fd1 100644
--- a/src/commands/status.test.ts
+++ b/src/commands/status.test.ts
@@ -4,6 +4,7 @@ import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest
 import type { PluginCompatibilityNotice } from "../plugins/status.js";
 import { createCompatibilityNotice } from "../plugins/status.test-fixtures.js";
 import { captureEnv, deleteTestEnvValue, setTestEnvValue } from "../test-utils/env.js";
+import type { StatusScanResult } from "./status.scan-result.js";
 
 let envSnapshot: ReturnType<typeof captureEnv>;
 
@@ -279,7 +280,15 @@ function createSessionStatusRows() {
   };
 }
 
-async function createMockStatusScanResult(params: { includePluginCompatibility?: boolean } = {}) {
+async function createMockStatusScanResult(
+  params: {
+    includePluginCompatibility?: boolean;
+    configDiagnostics?: {
+      path: string;
+      issues: Array<{ path: string; message: string }>;
+    } | null;
+  } = {},
+) {
   const cfg = mocks.loadConfig();
   const gatewayProbe = await mocks.probeGateway();
   const gatewayReachable = gatewayProbe.ok === true;
@@ -328,6 +337,7 @@ async function createMockStatusScanResult(params: { includePluginCompatibility?:
   return {
     cfg,
     sourceConfig: cfg,
+    configDiagnostics: params.configDiagnostics ?? null,
     secretDiagnostics: gatewayAuthWarning ? ["gateway.auth.token unavailable"] : [],
     osSummary: {
       platform: "darwin",
@@ -741,7 +751,7 @@ vi.mock("../config/config.js", () => ({
   readBestEffortConfig: vi.fn(async () => mocks.loadConfig()),
   readBestEffortConfigSnapshot: vi.fn(async () => {
     const config = mocks.loadConfig();
-    return { config, sourceConfig: config };
+    return { config, sourceConfig: config, configDiagnostics: null };
   }),
   resolveGatewayPort: vi.fn(() => 18789),
 }));
@@ -1063,6 +1073,24 @@ describe("statusCommand", () => {
     expect(auditParams?.includeChannelSecurity).toBe(true);
   });
 
+  it("includes invalid config diagnostics in JSON status only when present", async () => {
+    const { scanStatusJsonFast } = await import("./status.scan.fast-json.js");
+    const configDiagnostics = {
+      path: "/tmp/openclaw.json",
+      issues: [{ path: "gateway.port", message: "invalid" }],
+    };
+    vi.mocked(scanStatusJsonFast).mockResolvedValueOnce(
+      (await createMockStatusScanResult({ configDiagnostics })) as unknown as StatusScanResult,
+    );
+
+    await statusCommand({ json: true }, runtime as never);
+
+    expect(JSON.parse(getRuntimeLog(0)).configDiagnostics).toEqual(configDiagnostics);
+    runtimeLogMock.mockClear();
+    await statusCommand({ json: true }, runtime as never);
+    expect(JSON.parse(getRuntimeLog(0))).not.toHaveProperty("configDiagnostics");
+  });
+
   it("scopes usage resolution to the scanned config", async () => {
     const snapshotMock = resolveStatusRuntimeSnapshot as Mock;
     const usageMock = resolveStatusUsageSummary as Mock;
@@ -1100,6 +1128,52 @@ describe("statusCommand", () => {
     expect(mocks.runSecurityAudit).not.toHaveBeenCalled();
   });
 
+  it("prints invalid config diagnostics in default and deep text status only when present", async () => {
+    const { scanStatus } = await import("./status.scan.js");
+    const configDiagnostics = {
+      path: "/tmp/openclaw.json",
+      issues: [
+        {
+          path: "gateway.port",
+          message: "Invalid input: expected number, received string",
+        },
+      ],
+    };
+
+    for (const args of [{}, { deep: true }]) {
+      vi.mocked(scanStatus).mockResolvedValueOnce(
+        (await createMockStatusScanResult({ configDiagnostics })) as unknown as StatusScanResult,
+      );
+      const output = (await runStatusAndGetLogs(args)).join("\n");
+      expect(output).toContain("Config diagnostics:");
+      expect(output).toContain("Config file is invalid: /tmp/openclaw.json");
+      expect(output).toContain("gateway.port: Invalid input: expected number, received string");
+      expect(output).toContain("Fix: openclaw doctor --fix");
+    }
+
+    expect((await runStatusAndGetLogs()).join("\n")).not.toContain("Config diagnostics:");
+  });
+
+  it("prints invalid config diagnostics before a deep gateway-health failure", async () => {
+    const { scanStatus } = await import("./status.scan.js");
+    vi.mocked(scanStatus).mockResolvedValueOnce(
+      (await createMockStatusScanResult({
+        configDiagnostics: {
+          path: "/tmp/openclaw.json",
+          issues: [{ path: "gateway.port", message: "invalid" }],
+        },
+      })) as unknown as StatusScanResult,
+    );
+    vi.mocked(resolveStatusRuntimeSnapshot).mockResolvedValueOnce({
+      health: { error: "gateway health unavailable" },
+    } as never);
+
+    await expect(statusCommand({ deep: true }, runtime as never)).rejects.toThrow(
+      "gateway health unavailable",
+    );
+    expect(runtimeLogMock.mock.calls.flat().join("\n")).toContain("Config diagnostics:");
+  });
+
   it("includes the security audit for deep JSON status", async () => {
     await statusCommand({ json: true, deep: true }, runtime as never);
 
diff --git a/src/config/io.best-effort.test.ts b/src/config/io.best-effort.test.ts
index 626f0da06cc4..d8bf81877782 100644
--- a/src/config/io.best-effort.test.ts
+++ b/src/config/io.best-effort.test.ts
@@ -293,6 +293,7 @@ describe("readBestEffortConfig", () => {
 
       const snapshot = await readBestEffortConfigSnapshot({ observe: false });
 
+      expect(snapshot.configDiagnostics).toBeNull();
       expect(snapshot.sourceConfig.agents?.defaults?.contextPruning?.mode).toBeUndefined();
       expect(snapshot.config.agents?.defaults?.contextPruning?.mode).toBe("cache-ttl");
       expect(snapshot.config.agents?.defaults?.compaction?.mode).toBe("safeguard");
@@ -307,6 +308,26 @@ describe("readBestEffortConfig", () => {
       });
     });
   });
+
+  it("returns invalid config diagnostics with the best-effort fallback", async () => {
+    await withTempHome(async (home) => {
+      const configPath = await writeOpenClawConfig(home, {
+        gateway: { port: "abc" },
+      } as never);
+
+      const snapshot = await readBestEffortConfigSnapshot({ observe: false });
+
+      expect(snapshot.configDiagnostics).toEqual({
+        path: configPath,
+        issues: [
+          {
+            path: "gateway.port",
+            message: "Invalid input: expected number, received string",
+          },
+        ],
+      });
+    });
+  });
 });
 
 describe("readSourceConfigBestEffort", () => {
diff --git a/src/config/io.snapshot.ts b/src/config/io.snapshot.ts
index d79620958d82..22b482277dee 100644
--- a/src/config/io.snapshot.ts
+++ b/src/config/io.snapshot.ts
@@ -443,7 +443,14 @@ export async function readBestEffortConfigSnapshotFromContext(
 ): Promise<BestEffortConfigSnapshot> {
   const result = await readConfigFileSnapshotInternal(context);
   if (!result.snapshot.valid) {
-    return { config: result.snapshot.config, sourceConfig: result.snapshot.sourceConfig };
+    return {
+      config: result.snapshot.config,
+      sourceConfig: result.snapshot.sourceConfig,
+      configDiagnostics: {
+        path: result.snapshot.path,
+        issues: result.snapshot.issues,
+      },
+    };
   }
   return {
     config: context.finalizeLoadedRuntimeConfig(
@@ -452,6 +459,7 @@ export async function readBestEffortConfigSnapshotFromContext(
       }),
     ),
     sourceConfig: result.snapshot.sourceConfig,
+    configDiagnostics: null,
   };
 }
 
diff --git a/src/config/io.types.ts b/src/config/io.types.ts
index c5b9a50f74b7..0f6c21073932 100644
--- a/src/config/io.types.ts
+++ b/src/config/io.types.ts
@@ -6,7 +6,7 @@ import type {
   RuntimeConfigSnapshotRefreshOptions,
   RuntimeConfigWriteNotification,
 } from "./runtime-snapshot.js";
-import type { ConfigFileSnapshot, OpenClawConfig } from "./types.js";
+import type { ConfigFileSnapshot, ConfigValidationIssue, OpenClawConfig } from "./types.js";
 
 export type ParseConfigJson5Result = { ok: true; parsed: unknown } | { ok: false; error: string };
 
@@ -149,6 +149,7 @@ export type ReadConfigFileSnapshotWithPluginMetadataResult = {
 export type BestEffortConfigSnapshot = {
   config: OpenClawConfig;
   sourceConfig: OpenClawConfig;
+  configDiagnostics: { path: string; issues: ConfigValidationIssue[] } | null;
 };
 
 export type ConfigRecoveryCandidate = {

From 1353ce0995c69ffc12b2f28381c7553ba680b47c Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 12:50:26 -0700
Subject: [PATCH 083/124] feat: run Codex sessions on approved paired devices
 (#127202)

* feat(codex): execute paired-device sessions over node carrier

* fix(node-host): preserve approved invocation session identity

* fix(codex): observe paired-node execution leases before handshake

* fix: fence paired-device placement and Codex execution owners

* fix: satisfy paired-device placement CI ownership guards

* fix(codex): reject credentialed paired-node URL parameters

* fix(codex): fence nested remote HTTP session credentials

* fix(codex): scrub node process URLs and preserve plaintext HTTP

* test(codex): republish node inventory after capability approval
---
 .../OpenClawProtocol/GatewayModels.swift      |  16 +
 config/assertion-safety-baseline.txt          |   1 -
 docs/gateway/cloud-workers.md                 |  70 +-
 docs/nodes/index.md                           |  20 +-
 docs/plan/runners.md                          |  12 +-
 docs/plugins/codex-harness-reference.md       |  22 +
 docs/plugins/codex-harness-runtime.md         |  15 +
 docs/plugins/codex-harness.md                 |  90 +-
 docs/plugins/sdk-runtime.md                   |  18 +-
 extensions/codex/harness.test.ts              |  10 +-
 extensions/codex/harness.ts                   |  16 +-
 extensions/codex/index.test.ts                |  31 +-
 extensions/codex/index.ts                     |   6 +
 .../src/app-server/attempt-startup.test.ts    | 167 ++++
 .../codex/src/app-server/attempt-startup.ts   |  19 +-
 .../codex/src/app-server/config-parsing.ts    |  11 +
 extensions/codex/src/app-server/config.ts     |   1 +
 .../src/app-server/dynamic-tool-build.test.ts |  77 ++
 .../src/app-server/dynamic-tool-build.ts      |  36 +-
 .../app-server/run-attempt-connection.test.ts |  67 ++
 .../src/app-server/run-attempt-connection.ts  |  13 +-
 .../src/app-server/run-attempt-finalize.ts    |  13 +-
 .../src/app-server/run-attempt-resources.ts   |  36 +-
 .../codex/src/app-server/run-attempt-start.ts |  10 +-
 .../codex/src/app-server/run-attempt-types.ts |   2 +
 .../codex/src/app-server/run-attempt.ts       |  12 +-
 .../sandbox-exec-server-node-relay.test.ts    | 700 +++++++++++++++
 .../sandbox-exec-server-node-relay.ts         | 509 +++++++++++
 .../sandbox-exec-server-registry.ts           |  15 +-
 .../src/app-server/sandbox-exec-server.ts     | 287 +++++-
 .../app-server/sandbox-exec-server/types.ts   |  35 +-
 .../src/app-server/side-question.test.ts      |  40 +-
 .../codex/src/app-server/side-question.ts     |  33 +-
 .../codex/src/app-server/transport-stdio.ts   |  10 +-
 .../codex/src/node-exec-server.runtime.ts     | 287 ++++++
 extensions/codex/src/node-exec-server.test.ts | 673 ++++++++++++++
 extensions/codex/src/node-exec-server.ts      | 148 ++++
 .../src/schema/agents-models-skills.test.ts   |  48 +-
 .../src/schema/agents-models-skills.ts        |   9 +
 .../src/schema/environments.test.ts           |  25 +
 .../src/schema/environments.ts                |   6 +
 .../agent-tools.construction-routing.test.ts  |  40 +
 src/agents/agent-tools.ts                     |   4 +-
 src/agents/core-coding-tools.ts               |   6 +-
 src/agents/harness/types.ts                   |   8 +
 .../doctor-node-hosting-preconditions.test.ts |  96 +-
 .../doctor-node-hosting-preconditions.ts      |  30 +-
 src/gateway/node-invoke-plugin-policy.test.ts |  74 +-
 src/gateway/node-invoke-plugin-policy.ts      |  10 +
 ...nvironments.node-command-authority.test.ts | 112 +++
 src/gateway/server-methods/environments.ts    |  32 +-
 .../models-list-result.openai-routes.test.ts  |   8 +-
 src/gateway/server-methods/models.test.ts     |   9 +
 src/gateway/server-methods/nodes.invoke.ts    |   1 +
 .../sessions-dispatch.test-support.ts         |  32 +-
 .../server-methods/sessions-dispatch.ts       |  49 +-
 .../sessions.dispatch.device.test.ts          | 212 ++++-
 .../server-methods/sessions.dispatch.test.ts  |  39 +-
 src/gateway/server-plugins-node-runtime.ts    |   1 +
 ...-worker-placement-move-destination.test.ts | 142 +++
 ...erver-worker-placement-move-destination.ts |  81 ++
 .../server-worker-placement-startup.test.ts   |  65 --
 .../server-worker-placement-startup.ts        |  75 +-
 .../server.models-voicewake-misc.test.ts      |  10 +
 ...r.worker-placement-startup-context.test.ts |   2 +-
 .../device-placement-eligibility.ts           |  74 ++
 .../device-provider.test.ts                   |  22 +-
 .../worker-environments/device-provider.ts    |  19 +-
 .../worker-environments/environment-access.ts |   4 +-
 src/gateway/worker-environments/identity.ts   |   2 +-
 .../worker-environments/node-worker-tunnel.ts |  20 +-
 .../placement-dispatch-device.test.ts         | 238 ++++-
 .../placement-dispatch-startup.ts             |  37 +-
 .../placement-dispatch-test-harness.ts        |  17 +-
 .../worker-environments/placement-dispatch.ts |  32 +-
 .../placement-force-abandon.ts                |   1 +
 .../placement-move-abandon.test.ts            |  49 +
 .../placement-sandbox.test.ts                 | 306 +++++--
 .../worker-environments/placement-sandbox.ts  | 124 ++-
 .../placement-session-runtime.test.ts         | 146 +++
 .../placement-session-runtime.ts              |  44 +-
 .../placement-store-terminal.test.ts          | 114 ++-
 .../worker-environments/placement-store.ts    |  39 +-
 ...placement-store.turn-claim-closure.test.ts |  67 +-
 .../placement-turn-claims.ts                  |  23 +-
 .../worker-environments/provider-lifecycle.ts |  19 +-
 .../provider-lifecycle.types.ts               |   4 +-
 .../provider-node-provisioning.ts             |   6 +-
 .../provider-persisted-lease.ts               |   4 +-
 .../reclaimed-placement-redispatch.test.ts    |  52 ++
 .../reclaimed-placement-redispatch.ts         |  22 +
 .../worker-environments/service-contract.ts   |   9 +-
 .../worker-environments/service-validation.ts |   4 +-
 .../worker-environments/tunnel-contract.ts    |   4 +-
 .../worker-turn-launcher.test.ts              | 477 +++++++---
 .../worker-turn-launcher.ts                   |  32 +-
 .../workspace-result-finalize.ts              |  28 +-
 src/infra/node-duplex-framing.test.ts         |  86 ++
 src/infra/node-duplex-framing.ts              |  13 +-
 src/node-host/invoke-payload.test.ts          |  29 +-
 src/node-host/invoke-payload.ts               |   3 +
 src/node-host/invoke.test.ts                  |  66 ++
 src/node-host/invoke.ts                       |  28 +-
 .../node-worker-workspace-identity.ts         | 137 +++
 .../node-worker-workspace-retention.test.ts   | 106 +++
 src/node-host/node-worker-workspace.ts        | 102 +--
 src/node-host/runtime.ts                      |   6 +
 src/plugins/capability-provider.types.ts      |  10 +-
 src/plugins/plugin-registration.types.ts      |   1 +
 src/plugins/runtime/types.ts                  |   5 +-
 src/plugins/types.node-host.ts                |   8 +
 src/shared/session-types.ts                   |   2 +
 .../codex-node-exec-server.e2e.test.ts        | 834 ++++++++++++++++++
 .../session-placement-move-dialog.ts          |   2 +
 ...sion-page.environment-metadata.e2e.test.ts |  72 +-
 ui/src/i18n/locales/en.ts                     |   2 +-
 .../pages/chat/chat-pane-placement.runtime.ts |  29 +-
 ui/src/pages/chat/chat-pane-placement.test.ts | 259 +++++-
 .../new-session/device-placement.test.ts      |  52 ++
 ui/src/pages/new-session/device-placement.ts  |  32 +-
 ui/src/pages/new-session/discovery.test.ts    |  22 +
 ui/src/pages/new-session/discovery.ts         |  13 +-
 ui/src/pages/new-session/draft-place-state.ts |  31 +-
 .../new-session/draft-submission-flow.test.ts |   8 +-
 .../pages/new-session/model-control.test.ts   |  35 +
 ui/src/pages/new-session/model-control.ts     |   6 +-
 ui/src/pages/new-session/new-session-page.ts  |   1 +
 ui/src/pages/new-session/where-chip.test.ts   |  89 +-
 ui/src/pages/new-session/where-chip.ts        |   9 +-
 129 files changed, 8071 insertions(+), 820 deletions(-)
 create mode 100644 extensions/codex/src/app-server/sandbox-exec-server-node-relay.test.ts
 create mode 100644 extensions/codex/src/app-server/sandbox-exec-server-node-relay.ts
 create mode 100644 extensions/codex/src/node-exec-server.runtime.ts
 create mode 100644 extensions/codex/src/node-exec-server.test.ts
 create mode 100644 extensions/codex/src/node-exec-server.ts
 create mode 100644 src/gateway/server-methods/environments.node-command-authority.test.ts
 create mode 100644 src/gateway/server-worker-placement-move-destination.test.ts
 create mode 100644 src/gateway/server-worker-placement-move-destination.ts
 create mode 100644 src/gateway/worker-environments/device-placement-eligibility.ts
 create mode 100644 src/gateway/worker-environments/placement-session-runtime.test.ts
 create mode 100644 src/node-host/node-worker-workspace-identity.ts
 create mode 100644 test/e2e/qa-lab/runtime/codex-node-exec-server.e2e.test.ts

diff --git a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
index 2ff70bde0e5f..72281d0c4dc3 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
@@ -2201,6 +2201,7 @@ public struct EnvironmentSummary: Codable, Sendable {
     public let lastseenreason: String?
     public let trust: String?
     public let capabilities: [String]?
+    public let invocablecommands: [String]?
     public let desktop: Bool?
     public let issues: [[String: AnyCodable]]?
     public let worker: WorkerEnvironmentMetadata?
@@ -2220,6 +2221,7 @@ public struct EnvironmentSummary: Codable, Sendable {
         lastseenreason: String? = nil,
         trust: String? = nil,
         capabilities: [String]? = nil,
+        invocablecommands: [String]? = nil,
         desktop: Bool? = nil,
         issues: [[String: AnyCodable]]? = nil,
         worker: WorkerEnvironmentMetadata? = nil)
@@ -2238,6 +2240,7 @@ public struct EnvironmentSummary: Codable, Sendable {
         self.lastseenreason = lastseenreason
         self.trust = trust
         self.capabilities = capabilities
+        self.invocablecommands = invocablecommands
         self.desktop = desktop
         self.issues = issues
         self.worker = worker
@@ -2258,6 +2261,7 @@ public struct EnvironmentSummary: Codable, Sendable {
         case lastseenreason = "lastSeenReason"
         case trust
         case capabilities
+        case invocablecommands = "invocableCommands"
         case desktop
         case issues
         case worker
@@ -2297,6 +2301,7 @@ public struct EnvironmentsCreateResult: Codable, Sendable {
     public let lastseenreason: String?
     public let trust: String?
     public let capabilities: [String]?
+    public let invocablecommands: [String]?
     public let desktop: Bool?
     public let issues: [[String: AnyCodable]]?
     public let worker: WorkerEnvironmentMetadata?
@@ -2316,6 +2321,7 @@ public struct EnvironmentsCreateResult: Codable, Sendable {
         lastseenreason: String? = nil,
         trust: String? = nil,
         capabilities: [String]? = nil,
+        invocablecommands: [String]? = nil,
         desktop: Bool? = nil,
         issues: [[String: AnyCodable]]? = nil,
         worker: WorkerEnvironmentMetadata? = nil)
@@ -2334,6 +2340,7 @@ public struct EnvironmentsCreateResult: Codable, Sendable {
         self.lastseenreason = lastseenreason
         self.trust = trust
         self.capabilities = capabilities
+        self.invocablecommands = invocablecommands
         self.desktop = desktop
         self.issues = issues
         self.worker = worker
@@ -2354,6 +2361,7 @@ public struct EnvironmentsCreateResult: Codable, Sendable {
         case lastseenreason = "lastSeenReason"
         case trust
         case capabilities
+        case invocablecommands = "invocableCommands"
         case desktop
         case issues
         case worker
@@ -2393,6 +2401,7 @@ public struct EnvironmentsDestroyResult: Codable, Sendable {
     public let lastseenreason: String?
     public let trust: String?
     public let capabilities: [String]?
+    public let invocablecommands: [String]?
     public let desktop: Bool?
     public let issues: [[String: AnyCodable]]?
     public let worker: WorkerEnvironmentMetadata?
@@ -2412,6 +2421,7 @@ public struct EnvironmentsDestroyResult: Codable, Sendable {
         lastseenreason: String? = nil,
         trust: String? = nil,
         capabilities: [String]? = nil,
+        invocablecommands: [String]? = nil,
         desktop: Bool? = nil,
         issues: [[String: AnyCodable]]? = nil,
         worker: WorkerEnvironmentMetadata? = nil)
@@ -2430,6 +2440,7 @@ public struct EnvironmentsDestroyResult: Codable, Sendable {
         self.lastseenreason = lastseenreason
         self.trust = trust
         self.capabilities = capabilities
+        self.invocablecommands = invocablecommands
         self.desktop = desktop
         self.issues = issues
         self.worker = worker
@@ -2450,6 +2461,7 @@ public struct EnvironmentsDestroyResult: Codable, Sendable {
         case lastseenreason = "lastSeenReason"
         case trust
         case capabilities
+        case invocablecommands = "invocableCommands"
         case desktop
         case issues
         case worker
@@ -2505,6 +2517,7 @@ public struct EnvironmentsStatusResult: Codable, Sendable {
     public let lastseenreason: String?
     public let trust: String?
     public let capabilities: [String]?
+    public let invocablecommands: [String]?
     public let desktop: Bool?
     public let issues: [[String: AnyCodable]]?
     public let worker: WorkerEnvironmentMetadata?
@@ -2524,6 +2537,7 @@ public struct EnvironmentsStatusResult: Codable, Sendable {
         lastseenreason: String? = nil,
         trust: String? = nil,
         capabilities: [String]? = nil,
+        invocablecommands: [String]? = nil,
         desktop: Bool? = nil,
         issues: [[String: AnyCodable]]? = nil,
         worker: WorkerEnvironmentMetadata? = nil)
@@ -2542,6 +2556,7 @@ public struct EnvironmentsStatusResult: Codable, Sendable {
         self.lastseenreason = lastseenreason
         self.trust = trust
         self.capabilities = capabilities
+        self.invocablecommands = invocablecommands
         self.desktop = desktop
         self.issues = issues
         self.worker = worker
@@ -2562,6 +2577,7 @@ public struct EnvironmentsStatusResult: Codable, Sendable {
         case lastseenreason = "lastSeenReason"
         case trust
         case capabilities
+        case invocablecommands = "invocableCommands"
         case desktop
         case issues
         case worker
diff --git a/config/assertion-safety-baseline.txt b/config/assertion-safety-baseline.txt
index fbeb034a84ac..be6875c89154 100644
--- a/config/assertion-safety-baseline.txt
+++ b/config/assertion-safety-baseline.txt
@@ -3127,7 +3127,6 @@ src/gateway/worker-environments/node-worker-tunnel.ts	6
 src/gateway/worker-environments/node-worker-workspace-fallback.ts	2
 src/gateway/worker-environments/node-workspace-transfer-service.ts	1
 src/gateway/worker-environments/node-workspace-transfer-snapshot.ts	1
-src/gateway/worker-environments/placement-session-runtime.ts	1
 src/gateway/worker-environments/placement-state.ts	3
 src/gateway/worker-environments/placement-store.ts	1
 src/gateway/worker-environments/provider-lifecycle.ts	1
diff --git a/docs/gateway/cloud-workers.md b/docs/gateway/cloud-workers.md
index f70b93ce6f7c..c252d2c83e9c 100644
--- a/docs/gateway/cloud-workers.md
+++ b/docs/gateway/cloud-workers.md
@@ -7,7 +7,7 @@ status: active
 doc-schema-version: 1
 ---
 
-Cloud workers move a session's coding work onto a throwaway cloud machine while the session stays visible in the sidebar and its transcript remains owned by the Gateway. The bundled Crabbox provider boots the box, runs profile setup, and starts `openclaw connect --ephemeral`. The enrolled node then receives the Gateway's pinned worker bundle and hosts the same restricted `openclaw worker` children as any paired session-capable device.
+Cloud workers move a session's coding work onto a throwaway cloud machine while the session stays visible in the sidebar and its transcript remains owned by the Gateway. The bundled Crabbox provider boots the box, runs profile setup, and starts `openclaw connect --ephemeral`. In OpenClaw `worker-turn` mode, the enrolled node receives the Gateway's pinned worker bundle and hosts a restricted `openclaw worker` child. Eligible paired devices can instead carry Codex `remote-exec` without launching an OpenClaw worker child.
 
 Enrollment is environment-owned and replay-safe. The Gateway persists one setup identity before provider allocation, binds the first authenticated device identity to that exact environment, and reuses the durable device token when provisioning resumes. Initial enrollment and replay both enable worker hosting only for that node process; they do not change durable worker-host configuration. Reclaim or destroy releases the cloud lease and removes the environment-owned node pairing.
 
@@ -22,12 +22,12 @@ Cloud workers are opt-in. Until you configure a profile, clients hide the Cloud
 | Concern                            | OpenClaw `worker-turn` mode                          | Codex `remote-exec` mode                                |
 | ---------------------------------- | ---------------------------------------------------- | ------------------------------------------------------- |
 | Agent runtime and turn loop        | Cloud box (`openclaw worker`)                        | Gateway (Codex app-server)                              |
-| Command, filesystem, and HTTP work | Cloud box                                            | SSH-backed provider sandbox                             |
+| Command, filesystem, and HTTP work | Cloud box                                            | Paired device or SSH-backed provider sandbox            |
 | Model inference and provider auth  | Gateway, proxied by `{provider, model}` reference    | Gateway, including ChatGPT subscription or API-key auth |
 | Transcript and live session state  | Gateway, fed by the worker's replayable event stream | Gateway through the normal local harness path           |
 | Workspace file state               | Changed on the box; reconciled by the Gateway        | Changed remotely; reconciled by the Gateway             |
 
-The bundled Crabbox provider supports `worker-turn` through the node transport. Codex `remote-exec` remains available only with a provider that explicitly supports its SSH sandbox carrier; OpenClaw rejects a node-only profile before allocating a lease.
+The bundled Crabbox cloud provider supports `worker-turn` through the node transport. Codex `remote-exec` supports an explicitly authorized paired device through that device's authenticated duplex node channel, or a cloud provider that explicitly advertises an SSH-backed execution carrier. A Crabbox cloud profile still does not advertise Codex `remote-exec`.
 
 After Crabbox setup, the cloud node dials the Gateway's public TLS endpoint over outbound WebSocket. Worker control and workspace transfer use the authenticated node and worker channels, not a Gateway-created reverse tunnel or rsync. Crabbox itself may still require SSH reachability while its CLI runs the provider-owned setup command. Outbound internet access is provider policy; the default AWS profile can reach the internet unless you restrict its network or security group.
 
@@ -180,13 +180,59 @@ While a placement is active, OpenClaw automatically samples available space on t
 ### Runtime support
 
 - **OpenClaw** uses `worker-turn` placement. The restricted `openclaw worker` process runs each turn on the leased node and proxies inference through the Gateway.
-- **Codex** uses `remote-exec` placement only when the selected provider advertises an SSH-backed execution carrier. The bundled Crabbox node provider does not, so Codex dispatch to Crabbox fails before allocation.
+- **Codex** uses `remote-exec` placement on an eligible paired device, or with a cloud provider that advertises an SSH-backed execution carrier. The bundled Crabbox cloud profile supports only `worker-turn`, so selecting that profile for Codex still fails before allocation.
 
-The Control UI disables cloud destinations whose advertised mode does not match the selected runtime.
+The Control UI disables cloud destinations whose advertised mode does not match
+the selected runtime, including when moving an existing session. An
+incompatible move is rejected before the active source starts draining or
+changes its durable placement.
 
 Other runtimes remain unavailable unless their harness explicitly declares a cloud placement mode. Cloud targets are not offered for external CLI session catalogs. Remote-exec fails closed if the selected provider or placement sandbox is unavailable; it never falls back to running the operation on the Gateway host.
 
-The equivalent RPC flow is:
+### Codex on a paired device
+
+Paired-device Codex placement requires the `codex` plugin to be installed and
+enabled in both the Gateway's configuration and the node's own local
+configuration. Include `codex` in `plugins.allow` on either machine when that
+machine uses a plugin allowlist. It also requires a connected session-capable
+node that advertises `codex.exec-server`, and an explicit
+`gateway.nodes.commands.allow` entry for `codex.exec-server.stdio.v1`. Approve
+the node's updated pairing surface if needed. Before each exec-server launch,
+OpenClaw also requires the normal node invocation approval; denying that
+request does not start a process.
+
+Codex launches its exec-server directly, so paired-device placement does not
+consume an OpenClaw worker slot and remains eligible when those slots are full.
+OpenClaw `worker-turn` placement still requires an available worker slot.
+
+Approval permits process execution and filesystem access anywhere the node's
+operating system account allows. The exact placement workspace controls the
+starting directory and reconciled changes, not OS-level confinement. Trust the
+paired device, and use a separate least-privilege OS account when isolation is
+required.
+
+Choose the device in the Control UI **Place** picker or dispatch a
+managed-worktree session with an authorized operator connection:
+
+```bash
+openclaw gateway call sessions.dispatch \
+  --params '{"key":"agent:main:device-work","deviceId":"<paired-device-id>"}'
+```
+
+The Codex app-server, model connection, provider credentials, and transcript
+remain on the Gateway. The paired node runs the managed Codex exec-server in
+the transferred workspace and receives only sanitized process, filesystem,
+capability-discovery, and HTTP operations over the existing node channel. It
+does not launch an OpenClaw worker child. Credential-bearing HTTP requests are
+rejected before they reach the paired device; run authenticated requests on the
+Gateway or use an intentionally credential-free endpoint. Normal Codex turns
+are supported, but `/btw` side questions are not yet placement-bound and fail
+visibly. Completed changes return through the same placement workspace
+reconciliation as worker turns. See
+[Run Codex on a paired device](/plugins/codex-harness#run-codex-on-a-paired-device)
+for the exact allowlist configuration and lifecycle.
+
+For cloud-profile placement, the equivalent RPC flow is:
 
 Create a session with a managed worktree, then dispatch it. Profile dispatch requires `operator.admin` and is available only while at least one worker profile is configured:
 
@@ -211,7 +257,7 @@ openclaw gateway call sessions.dispatch \
 
 The bundled Crabbox provider advertises whatever machine classes the configured Crabbox binary reports for the selected backend, preserving Crabbox's size order. For example, a catalog containing `tiny`, `small`, `standard`, `fast`, `large`, and `beast` produces those six picker rows in that order; if Crabbox reports `standard` as 32 vCPU · 64 GB, that shape appears beside the class. Older binaries that publish no matching class catalog retain the label-only `standard`, `fast`, `large`, and `beast` fallback. You can also pass a provider-native server or instance type such as `c7a.24xlarge`; Crabbox treats any other non-empty class as that exact type. The selected value is fixed for that placement and reused by safe provisioning retries. `machineClass` is valid only with `profileId`, not `deviceId`.
 
-`sessions.dispatch` closes local turn admission, drains active work, validates the eligible Git workspace inventory, provisions the lease, runs setup, enrolls the node, pushes the Gateway bundle, syncs the workspace, and returns once the placement reaches `active` ownership. Inventory validation happens before provider allocation and reports an invalid request with an actionable size or entry limit when the workspace cannot be dispatched. Budget several minutes for the first dispatch; leases and content-addressed bundles are reused where safe. After that, talk to the session as usual. OpenClaw turns route to the worker process; supported SSH-backed providers may still carry Codex remote-exec.
+`sessions.dispatch` closes local turn admission, drains active work, validates the eligible Git workspace inventory, provisions the lease, runs setup, enrolls the node, pushes the Gateway bundle when worker hosting requires it, syncs the workspace, and returns once the placement reaches `active` ownership. Inventory validation happens before provider allocation and reports an invalid request with an actionable size or entry limit when the workspace cannot be dispatched. Budget several minutes for the first cloud dispatch; leases and content-addressed bundles are reused where safe. After that, talk to the session as usual. OpenClaw turns route to the worker process; Codex native operations run on the authorized paired device or supported SSH-backed provider.
 
 Completed cloud turns reconcile eligible, size-bounded workspace files back into the session's managed worktree before the turn claim is released. Worker-turn uses its terminal worker event to create the durable pending-result fence. Remote-exec waits for workspace quiescence and enters the same reconciliation flow after the local Codex attempt. Before applying the result, the Gateway stages complete authenticated base/current manifests plus each changed resulting blob as a Git ref under `refs/openclaw/worker-results/`; deletions are represented by the manifests and need no blob. This keeps the cloud delta recoverable even if the Gateway stops during the apply without duplicating unchanged baseline content. Workspace results use Git file semantics: regular files, executable bits, symlinks, additions, changes, and deletions are retained, while empty directories and other directory modes are not. The resulting file changes remain in the managed worktree for normal review and commit.
 
@@ -226,10 +272,15 @@ To continue the same session somewhere else, open the **Runs on Cloud** chip and
 An active paired-device placement stays `active` when its runner disconnects.
 Control UI shows **Device offline** and **Waiting for device to reconnect; retry
 after it returns**. Waiting is the default and keeps the remote owner and
-workspace intact. **Continue on Gateway…** is explicitly destructive: after a
+workspace intact. Any in-flight Codex `remote-exec` attempt fails visibly, its
+node exec-server and child processes are terminated, and reconnecting the same
+paired device allows a fresh attempt only; the disconnected stdio session is
+never resumed. **Continue on Gateway…** is explicitly destructive: after a
 data-loss confirmation, it abandons the exact offline device owner and resumes
 from the last Gateway-synced workspace without replay. Unsynced device files
-and in-flight work may be lost. If the device is already available, use the
+and in-flight work may be lost. This explicit abandonment also fences an active
+local Codex turn claim without waiting for an acknowledgment from the offline
+node. If the device is already available, use the
 ordinary reconcile-first move instead.
 
 When the work is complete and no turn is running, choose **Stop cloud worker…** from the same chip. The Gateway performs one final workspace reconciliation before it destroys the environment. A placement already in `draining` or `reconciling` is finishing teardown; wait for its badge to become `reclaimed` before deleting the session.
@@ -290,6 +341,7 @@ The desktop never gains public ingress. The node reads `/var/lib/crabbox/vnc.pas
 - **Gateway-owned tool authority.** In worker-turn mode, the Gateway projects current profile, provider, agent, group, sender, sandbox, delegation, inherited, and runtime-cap policy over the worker's fixed coding-tool catalog before every turn. The launch envelope carries only that final closed-vocabulary subset. Explicitly capped scheduled turns reuse their trusted owner-group context without sending that identity to the box or reapplying a fresh sender overlay. Tools outside the worker catalog remain unavailable; an empty result runs with no tools.
 - **Minted credentials, hashed at rest.** Each dispatch mints a worker credential; the Gateway stores only its hash. Credential rotation and owner-epoch fencing guarantee at most one live owner per session — a stale worker that reconnects is fenced, never merged.
 - **Environment-bound enrollment.** One short-lived node-only setup credential is bound to the durable environment before allocation. Its first authenticated Ed25519 device identity is recorded atomically with setup completion; replay cannot substitute an unrelated node.
+- **Explicit Codex device authorization.** Paired-device remote execution requires an explicitly allowed `codex.exec-server.stdio.v1` command, an approved pairing surface, and normal node invocation approval. The managed exec-server starts with a fresh private home and sanitized environment; allow-once never grants a later launch. Its managed workspace is not an OS sandbox: approved execution can access processes and files allowed to the node account, so use a separate least-privilege account when isolation is required.
 - **No standing model, forge, or cloud credentials on the box.** OpenClaw worker turns proxy inference by `{provider, model}` reference. Codex remote-exec keeps the app-server plus ChatGPT subscription or API-key auth on the Gateway and sends only sandbox operations to the box. Remote-exec requires prepared auth and rejects ambient auth fallback. Workspace git commits are authored without forge credentials, and Crabbox AWS lease metadata is checked authoritatively for an instance role before setup. Keep setup commands credential-free too.
 - **Gateway-owned GitHub publication.** Publication credentials stay in the effective managed or native GitHub profile on the Gateway. The broker disables repository hooks, refuses configured Git clean filters, uses a temporary index and `git commit-tree`, pushes only a reconstructed public HTTPS URL with a command-local `gh auth git-credential` helper, and never writes a bearer token to argv, a remote URL, `.git/config`, a worker payload, or a transcript.
 - **Provider-owned egress.** Gateway-proxied inference removes any OpenClaw need for direct model access, but OpenClaw does not rewrite provider firewalls. Restrict outbound traffic in the worker provider when the task requires it.
diff --git a/docs/nodes/index.md b/docs/nodes/index.md
index 76ac2d8f2033..68cbba42ed2c 100644
--- a/docs/nodes/index.md
+++ b/docs/nodes/index.md
@@ -94,7 +94,7 @@ A Gateway can remain healthy for browser users while node hosting is unavailable
 - **Machine authentication:** Tailscale identity headers do not authenticate node-role connections. In `gateway.auth.mode: "trusted-proxy"`, a new node also cannot supply the proxy's user identity headers. To use a shared token, switch to token mode and configure `gateway.auth.token` with a SecretRef; trusted-proxy mode rejects mixed token configuration. A trusted-proxy Gateway can use `gateway.auth.password` only for clean loopback/direct callers. See [trusted-proxy mixed token configuration](/gateway/trusted-proxy-auth#mixed-token-configuration).
 - **Node onboarding URL:** With `gateway.bind: "loopback"`, configure Tailscale Serve, `gateway.remote.url`, or `plugins.entries.device-pair.config.publicUrl` before minting a join code. Otherwise `openclaw devices join-code` reports: `Gateway is only bound to loopback. Set gateway.bind=lan, enable tailscale serve, or configure plugins.entries.device-pair.config.publicUrl.`
 - **Node onboarding plugin:** Join codes and `openclaw connect` require the bundled `device-pair` plugin. If it is disabled or excluded by plugin policy, set `plugins.entries.device-pair.enabled: true`, make sure `device-pair` is allowed, and restart the Gateway.
-- **Device session runtime:** Paired-device runners host only the embedded OpenClaw runtime. Give at least one selected agent/model route `agentRuntime.id: "openclaw"`; Codex and ACPX routes cannot dispatch to a paired device. Runtime policy belongs on provider/model routes, not the ignored whole-agent runtime keys. Multi-agent rosters must also set `agents.ownership: "explicit"`. See [runtime policy](/gateway/config-agents#runtime-policy).
+- **Device session runtime:** Paired-device runners support the embedded OpenClaw runtime and explicitly authorized Codex `remote-exec`; ACPX routes cannot dispatch to a paired device. Codex requires `codex.exec-server.stdio.v1` in `gateway.nodes.commands.allow` plus its normal pairing and invocation approvals. Runtime policy belongs on provider/model routes, not the ignored whole-agent runtime keys. Multi-agent rosters must also set `agents.ownership: "explicit"`. See [Codex paired-device placement](/plugins/codex-harness#run-codex-on-a-paired-device) and [runtime policy](/gateway/config-agents#runtime-policy).
 - **Edge routing:** When a reverse proxy or access edge fronts the Gateway, the node must satisfy edge auth on the join request, its main Gateway WebSocket, and the worker WebSocket. Keep WebSocket upgrade enabled for `/__openclaw__/worker`. You can instead exempt `/j/*` and `/__openclaw__/worker` from edge identity auth because both routes enforce their own short-lived credentials. See [worker protocol](/gateway/protocol#worker-role-and-closed-protocol).
 
 For a Cloudflare Access-fronted Gateway:
@@ -496,11 +496,15 @@ most two worker processes by default. A third launch waits up to 10 seconds for
 a durable slot; while both slots are occupied, the node remains available for
 status and cancellation but is not selected for a new session turn.
 
-The picker derives every device row from `environments.list`. A device is
-selectable only when current inventory reports status `available`,
-`sessionHost: true`, valid exact worker slots, and at least one available slot.
-Connected non-hosts, saturated hosts, hosts without current capacity,
-update-required or otherwise outdated hosts, and unavailable hosts remain
+The picker derives every device row from `environments.list`. Every selected
+runtime requires an available, connected paired session host. OpenClaw worker
+turns additionally require valid exact worker slots with at least one free
+slot. Codex paired-device execution launches its exec-server directly, so it
+does not consume or require a worker slot; instead, its required command must
+appear in the node's effective `invocableCommands`, not merely its declared
+capabilities. A declared command is usable only when the approved pairing and
+Gateway command allowlist both authorize it. Connected non-hosts, ineligible
+or saturated hosts, update-required devices, and unavailable hosts remain
 visible but disabled with an actionable reason. Enable hosting with
 `openclaw connect --service --session-host` or the `nodeHost.workerRuns`
 setting, then restart the node host. Update-required hosts must be upgraded and
@@ -520,8 +524,8 @@ process-current, not a terminal placement state. `sessions.list` and
 until that exact current-v6 node runner reconnects. Gateway restart therefore
 shows an active device placement as offline until reconnect; current inventory
 then changes the projection to `available` and emits a session refresh. Exact
-worker slots gate new placements only and do not affect availability of a
-session the device already owns.
+worker slots gate only new placements whose runtime consumes a worker slot;
+they do not affect Codex remote execution or an existing session's availability.
 
 Control UI shows **Device offline** and waits by default without giving up the
 placement, workspace, or authority. Retry the next turn after the device
diff --git a/docs/plan/runners.md b/docs/plan/runners.md
index fa584c401dd8..bf563bcf5c16 100644
--- a/docs/plan/runners.md
+++ b/docs/plan/runners.md
@@ -410,11 +410,13 @@ The bundled Crabbox provider now boots the box and runs
 directory. The Gateway persists one replay-safe setup identity, atomically
 binds the authenticated device identity to the worker environment, pushes the
 current bundle through the node channel, and removes the node role after
-provider teardown. `destroy` = release lease plus pairing cleanup. Codex
-remote-exec fails before allocation because it still requires an SSH-backed
-provider. The replaced reverse-tunnel/rsync cloud carrier has been deleted.
-Distinct stable SSH, OpenShell, Claude, and exec-host contracts remain until
-the missing node exec-server carrier supplies and proves equivalent behavior.
+provider teardown. `destroy` = release lease plus pairing cleanup. Codex now
+supports paired-device `remote-exec` over the approved duplex node carrier;
+disconnect ends the attempt, and reconnect starts a fresh attempt without
+resume. Crabbox cloud profiles remain `worker-turn` only. The replaced
+reverse-tunnel/rsync cloud carrier has been deleted. Distinct stable SSH,
+OpenShell, Claude, and exec-host contracts remain intact; broader replacement
+and reconnect or resume are later work.
 
 ## What the adversarial reviews killed or reshaped
 
diff --git a/docs/plugins/codex-harness-reference.md b/docs/plugins/codex-harness-reference.md
index 45fdec3ff0f9..db304bddf313 100644
--- a/docs/plugins/codex-harness-reference.md
+++ b/docs/plugins/codex-harness-reference.md
@@ -482,6 +482,28 @@ This preview path is local-only. A remote WebSocket app-server cannot reach
 the loopback exec-server unless it is running on the same host, so OpenClaw
 rejects that combination.
 
+Paired-device `remote-exec` placement is a separate, placement-owned execution
+path and does not require `appServer.experimental.sandboxExecServer`. The
+Gateway keeps Codex app-server and provider auth local, while the authorized
+paired device runs the managed Codex exec-server over its existing duplex node
+connection. It requires explicit `gateway.nodes.commands.allow` authorization
+for `codex.exec-server.stdio.v1`, the approved pairing surface, and normal node
+invocation approval. The node receives a fresh private home and sanitized
+environments, never Gateway provider, cloud, or GitHub credentials. A lost
+node connection terminates the attempt and process instead of resuming it.
+Each paired-device attempt uses its own Gateway app-server client because
+Codex can register a remote environment but cannot remove one from a running
+app-server. The device exec-server does not consume an OpenClaw worker slot.
+HTTP requests containing authentication, cookies, API keys, or other
+credential-bearing headers are rejected before reaching the device; use a
+Gateway-owned authenticated request or a credential-free endpoint instead.
+Normal Codex turns are supported, but `/btw` side questions are unavailable
+until they can be bound to the active placement.
+The managed placement workspace is not an OS sandbox: approved processes and
+files have the node account's full access. Use a separate least-privilege node
+account when isolation is required.
+See [Run Codex on a paired device](/plugins/codex-harness#run-codex-on-a-paired-device).
+
 ## Auth and environment isolation
 
 In the default per-agent home, managed stdio launches use Codex's ephemeral
diff --git a/docs/plugins/codex-harness-runtime.md b/docs/plugins/codex-harness-runtime.md
index 6eb7d708309b..83e8ddab232c 100644
--- a/docs/plugins/codex-harness-runtime.md
+++ b/docs/plugins/codex-harness-runtime.md
@@ -223,6 +223,21 @@ process. Failed environment registration never falls back to host execution.
 See [Sandboxed native execution](/plugins/codex-harness-reference#sandboxed-native-execution)
 for configuration and local-only transport restrictions.
 
+Paired-device `remote-exec` is separate from the experimental local sandbox
+flag: Codex app-server and model auth stay on the Gateway, while an explicitly
+authorized managed exec-server on the node owns process, filesystem, capability,
+and credential-free HTTP operations. The Gateway rejects authentication,
+cookie, API-key, and other sensitive HTTP headers before they reach the node;
+authenticated HTTP must run on the Gateway. The existing duplex node channel
+carries the Codex JSON-RPC stream without starting an OpenClaw worker child or
+consuming a worker slot. Each attempt owns an isolated Gateway app-server
+client so its remote environment registration retires with that attempt.
+Disconnect ends the active attempt and its remote processes; reconnect allows
+only a fresh attempt. Normal Codex turns work, but `/btw` side questions fail
+closed because they are not yet placement-bound. The placement workspace does
+not confine execution: process and filesystem access remain bounded only by the
+node's operating system account.
+
 ## V1 support contract
 
 Supported in Codex runtime v1:
diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md
index 5ff04206fcfc..d8ab79825be3 100644
--- a/docs/plugins/codex-harness.md
+++ b/docs/plugins/codex-harness.md
@@ -45,8 +45,10 @@ When no OpenClaw sandbox is active, OpenClaw starts Codex app-server threads
 with Codex native code mode enabled (code-mode-only stays off by default), so
 native workspace/code capabilities remain available alongside OpenClaw
 dynamic tools routed through the app-server `item/tool/call` bridge. An
-active OpenClaw sandbox or restricted tool policy disables native code mode
-entirely unless you opt into the experimental sandbox exec-server path.
+ordinary OpenClaw sandbox or restricted tool policy disables native code mode
+unless you opt into the experimental sandbox exec-server path. Paired-device
+`remote-exec` instead uses its placement-owned environment without that
+experimental flag.
 
 Eligible native-shell turns also retain `gateway_exec` and `gateway_process`
 as a distinct OpenClaw execution path. Use `gateway_exec` only when a command
@@ -152,6 +154,90 @@ Restart the gateway after changing plugin config. If a chat already has a
 session, run `/new` or `/reset` first so the next turn resolves the harness
 from current config.
 
+## Run Codex on a paired device
+
+Codex sessions can place native command, filesystem, capability-discovery, and
+HTTP execution on an eligible paired device while the Codex app-server, model
+inference, provider authentication, and session transcript stay on the Gateway.
+This is session-wide `remote-exec` placement, not `node_exec` or
+`tools.exec.host: "node"`.
+
+Install and enable the Codex plugin in both the Gateway's configuration and the
+paired node's own local configuration. If either machine uses `plugins.allow`,
+include `codex` in that machine's allowlist. On the Gateway, explicitly allow
+the high-risk node command:
+
+```json5
+{
+  gateway: {
+    nodes: {
+      commands: {
+        allow: ["codex.exec-server.stdio.v1"],
+      },
+    },
+  },
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+      },
+    },
+  },
+}
+```
+
+The paired node must enable session hosting and advertise the `codex.exec-server`
+capability and `codex.exec-server.stdio.v1` command. If enabling the plugin
+changes an existing node's command surface, reconnect the node, inspect
+`openclaw nodes pending`, and approve the updated pairing with
+`openclaw nodes approve <requestId>`. The persistent command allowlist does not
+replace the normal node invocation approval: deny starts no Codex process, and
+allow-once authorizes exactly one exec-server launch.
+
+Codex launches its node exec-server directly rather than starting an OpenClaw
+worker, so a paired host remains eligible when all worker slots are occupied.
+The command must still be effectively invocable: declaring it without the
+approved pairing surface and Gateway allowlist is insufficient.
+
+Approval grants access to any process or file available to the node's operating
+system account. The verified placement workspace sets the working directory
+and reconciliation scope; it does not sandbox or confine that access. Pair only
+trusted devices, and run the node under a separate least-privilege OS account
+when isolation is required.
+
+Choose the paired device in the Control UI **Place** picker, or dispatch an
+existing managed-worktree session explicitly:
+
+```bash
+openclaw gateway call sessions.dispatch \
+  --params '{"key":"agent:main:device-work","deviceId":"<paired-device-id>"}'
+```
+
+The node starts the same managed, pinned Codex binary with
+`codex exec-server --listen stdio` in the placement workspace. The Gateway
+relays complete Codex JSON-RPC messages through the existing authenticated,
+approval-gated duplex node channel, with a 64 MiB limit per message. It does not
+start an OpenClaw worker child, open a reverse tunnel, or copy provider, cloud,
+or GitHub credentials to the device. Authenticated remote HTTP is unavailable:
+the Gateway rejects requests containing bearer/OAuth authorization, cookies,
+API keys, or other sensitive authentication headers before sending them to the
+node. Run authenticated HTTP on the Gateway, or use an intentionally
+credential-free endpoint. The node process uses a fresh private
+`HOME` and `CODEX_HOME` that are removed after the attempt, and both its launch
+environment and requested child-process environments are sanitized. Completed
+filesystem changes reconcile back into the Gateway-owned managed worktree.
+
+Disconnecting the node, closing the app-server connection, cancelling the turn,
+or retiring the plugin ends that Codex attempt visibly and terminates its remote
+exec-server process. Each paired-device attempt owns an isolated Gateway
+app-server client, preventing remote environment registrations from
+accumulating across attempts. Reconnecting the same paired device permits a
+fresh attempt; it never resumes the disconnected stdio connection or its
+processes. Normal Codex turns are supported, but `/btw` side questions are not
+yet bound to paired-device placement and fail with an actionable explanation.
+See [Cloud workers and paired-device placement](/gateway/cloud-workers) and
+[Node command policy](/nodes#command-policy).
+
 ## Share threads with Codex Desktop and CLI
 
 The default `appServer.homeScope: "agent"` isolates each OpenClaw agent from
diff --git a/docs/plugins/sdk-runtime.md b/docs/plugins/sdk-runtime.md
index e06a243b06ec..43c991d768ec 100644
--- a/docs/plugins/sdk-runtime.md
+++ b/docs/plugins/sdk-runtime.md
@@ -536,12 +536,18 @@ snapshots; OpenClaw owns all persistence and lifecycle coordination.
 
     `openDuplex` accepts the same node, command, parameters, timeout,
     idempotency key, session key, caller signal, and requested scopes as
-    `nodes.invoke`, plus an optional `maxMessageBytes`. The limit defaults to
-    100 MiB and can be reduced, but never increased beyond 100 MiB. OpenClaw
-    splits each binary message into ordered 8 KiB payload fragments that fit the
-    existing 16 KiB transport-frame limit; callers always send and receive
-    complete `Uint8Array` messages. Concurrent sends preserve message
-    boundaries.
+    `nodes.invoke`, plus optional `maxMessageBytes` and
+    `maxOutstandingDeliveryBytes` limits. The per-message limit defaults to
+    100 MiB and can be reduced, but never increased beyond 100 MiB.
+    `maxOutstandingDeliveryBytes` bounds the combined size of complete messages
+    whose asynchronous listener callbacks have not settled; it defaults to
+    `maxMessageBytes`, cannot be smaller than that limit, and cannot exceed
+    100 MiB. A protocol that can follow a maximum-sized response with a bounded
+    asynchronous notification may request a larger outstanding-delivery budget
+    without raising its per-message ceiling. OpenClaw splits each binary message
+    into ordered 8 KiB payload fragments that fit the existing 16 KiB
+    transport-frame limit; callers always send and receive complete
+    `Uint8Array` messages. Concurrent sends preserve message boundaries.
 
     Register the channel's single message listener immediately after
     `openDuplex` resolves. Before a listener is registered, OpenClaw buffers at
diff --git a/extensions/codex/harness.test.ts b/extensions/codex/harness.test.ts
index ef24f197506b..152f39c10e20 100644
--- a/extensions/codex/harness.test.ts
+++ b/extensions/codex/harness.test.ts
@@ -34,9 +34,13 @@ describe("Codex agent harness supports()", () => {
 
   it("publishes provider ids for lightweight auto selection", () => {
     expect(harness.autoSelection?.providerIds).toEqual(["codex", "openai"]);
-    expect(
-      (harness as typeof harness & { cloudPlacement?: { mode: "remote-exec" } }).cloudPlacement,
-    ).toEqual({ mode: "remote-exec" });
+    expect(harness.cloudPlacement).toEqual({
+      mode: "remote-exec",
+      devicePlacement: {
+        requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+        consumesWorkerSlot: false,
+      },
+    });
   });
 
   it("keeps computer-control denies out of the native-surface exemption", () => {
diff --git a/extensions/codex/harness.ts b/extensions/codex/harness.ts
index 942e6ab55077..a619231e9f94 100644
--- a/extensions/codex/harness.ts
+++ b/extensions/codex/harness.ts
@@ -49,10 +49,6 @@ const CODEX_APP_SERVER_CONTEXT_ENGINE_HOST_CAPABILITIES = [
   "thread-bootstrap-projection",
 ] as const satisfies readonly ContextEngineHostCapability[];
 
-type CodexAppServerAgentHarness = AgentHarnessV2 & {
-  cloudPlacement?: { mode: "remote-exec" };
-};
-
 type CodexAppServerAgentHarnessOptions = {
   id?: string;
   label?: string;
@@ -124,11 +120,17 @@ export function createCodexAppServerAgentHarness(
     resolvePluginConfigObject(config, "codex") ??
     options.resolvePluginConfig?.() ??
     options.pluginConfig;
-  const harness: CodexAppServerAgentHarness = {
+  const harness: AgentHarnessV2 = {
     id: harnessRuntimeId,
     label: options?.label ?? "Codex agent harness",
     autoSelection: { providerIds: [...providerIds] },
-    cloudPlacement: { mode: "remote-exec" },
+    cloudPlacement: {
+      mode: "remote-exec",
+      devicePlacement: {
+        requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+        consumesWorkerSlot: false,
+      },
+    },
     delegatedExecutionPluginIds: ["voice-call"],
     contextEngineHostCapabilities: CODEX_APP_SERVER_CONTEXT_ENGINE_HOST_CAPABILITIES,
     conversationToolPolicySupport: "exact",
@@ -264,6 +266,7 @@ export function createCodexAppServerAgentHarness(
       return runCodexAppServerAttempt(params, {
         bindingStore: options.bindingStore,
         pluginConfig: resolveAttemptPluginConfig(params.config),
+        runtime: sessionRuntime,
         runtimeModelId: readCodexRuntimeModelId(params.model, params.modelId),
         nativeHookRelay: { enabled: true },
       });
@@ -303,6 +306,7 @@ export function createCodexAppServerAgentHarness(
       return runCodexAppServerSideQuestion(params, {
         bindingStore: options.bindingStore,
         pluginConfig: options?.resolvePluginConfig?.() ?? options?.pluginConfig,
+        runtime: sessionRuntime,
         runtimeModelId: readCodexRuntimeModelId(params.runtimeModel, params.model),
         nativeHookRelay: { enabled: true },
       });
diff --git a/extensions/codex/index.test.ts b/extensions/codex/index.test.ts
index bc9991123aa4..12028b187b64 100644
--- a/extensions/codex/index.test.ts
+++ b/extensions/codex/index.test.ts
@@ -85,6 +85,7 @@ describe("codex plugin", () => {
   it("registers request-scoped surfaces with explicit multi-agent ownership", () => {
     const registerAgentHarness = vi.fn();
     const registerNodeHostCommand = vi.fn();
+    const registerNodeInvokePolicy = vi.fn();
     const registerSessionCatalog = vi.fn();
 
     expect(() =>
@@ -98,6 +99,7 @@ describe("codex plugin", () => {
           runtime: createCodexTestRuntime(() => explicitAgentConfig),
           registerAgentHarness,
           registerNodeHostCommand,
+          registerNodeInvokePolicy,
           registerSessionCatalog,
         }),
       ),
@@ -110,8 +112,26 @@ describe("codex plugin", () => {
         "codex.appServer.threads.list.v1",
         "codex.appServer.thread.turns.list.v1",
         "codex.terminal.resume.v1",
+        "codex.exec-server.stdio.v1",
       ]),
     );
+    const nodeExecServerCommand = registerNodeHostCommand.mock.calls
+      .map(([command]) => command)
+      .find((command) => command.command === "codex.exec-server.stdio.v1");
+    expect(nodeExecServerCommand).toMatchObject({
+      command: "codex.exec-server.stdio.v1",
+      cap: "codex.exec-server",
+      dangerous: true,
+      duplex: true,
+    });
+    const nodeExecServerPolicy = registerNodeInvokePolicy.mock.calls
+      .map(([policy]) => policy)
+      .find((policy) => policy.commands.includes("codex.exec-server.stdio.v1"));
+    expect(nodeExecServerPolicy).toMatchObject({
+      commands: ["codex.exec-server.stdio.v1"],
+      dangerous: true,
+    });
+    expect(nodeExecServerPolicy.defaultPlatforms).toBeUndefined();
   });
 
   it("proactively monitors an explicitly configured remote websocket app-server", () => {
@@ -286,7 +306,11 @@ describe("codex plugin", () => {
     const nodeCommands = registerNodeHostCommand.mock.calls.map(
       ([command]) => (command as { command: string }).command,
     );
-    expect(nodeCommands).toEqual(["codex.cli.sessions.list", "codex.cli.session.resume"]);
+    expect(nodeCommands).toEqual([
+      "codex.cli.sessions.list",
+      "codex.cli.session.resume",
+      "codex.exec-server.stdio.v1",
+    ]);
     expect(nodeCommands).not.toContain("codex.appServer.threads.list.v1");
     expect(nodeCommands).not.toContain("codex.appServer.thread.turns.list.v1");
     expect(registerSessionCatalog).not.toHaveBeenCalled();
@@ -938,6 +962,7 @@ describe("codex plugin", () => {
         },
       },
     };
+    const runtime = createCodexTestRuntime(() => liveConfig);
     plugin.register(
       createTestPluginApi({
         id: "codex",
@@ -945,7 +970,7 @@ describe("codex plugin", () => {
         source: "test",
         config: {},
         pluginConfig: { codexPlugins: { enabled: false } },
-        runtime: createCodexTestRuntime(() => liveConfig),
+        runtime,
         registerAgentHarness,
         registerCommand: vi.fn(),
         registerMediaUnderstandingProvider: vi.fn(),
@@ -967,6 +992,8 @@ describe("codex plugin", () => {
       {
         bindingStore: expect.any(Object),
         pluginConfig: liveConfig.plugins.entries.codex.config,
+        runtime,
+        runtimeModelId: undefined,
         nativeHookRelay: { enabled: true },
       },
     );
diff --git a/extensions/codex/index.ts b/extensions/codex/index.ts
index a3d2bc2d8f87..784e36ad9025 100644
--- a/extensions/codex/index.ts
+++ b/extensions/codex/index.ts
@@ -44,6 +44,10 @@ import {
   resumeCodexCliSessionOnNode,
   resolveCodexCliSessionForBindingOnNode,
 } from "./src/node-cli-sessions.js";
+import {
+  createCodexNodeExecServerCommand,
+  createCodexNodeExecServerInvokePolicy,
+} from "./src/node-exec-server.js";
 import {
   createCodexSessionCatalogControl,
   createCodexSessionCatalogNodeHostCommands,
@@ -260,6 +264,8 @@ export default definePluginEntry({
     for (const policy of createCodexCliSessionNodeInvokePolicies()) {
       api.registerNodeInvokePolicy(policy);
     }
+    api.registerNodeHostCommand(createCodexNodeExecServerCommand());
+    api.registerNodeInvokePolicy(createCodexNodeExecServerInvokePolicy());
     api.registerCommand(
       createCodexCommand({
         pluginConfig: api.pluginConfig,
diff --git a/extensions/codex/src/app-server/attempt-startup.test.ts b/extensions/codex/src/app-server/attempt-startup.test.ts
index 3558d07abadc..b85ad4644d38 100644
--- a/extensions/codex/src/app-server/attempt-startup.test.ts
+++ b/extensions/codex/src/app-server/attempt-startup.test.ts
@@ -8,6 +8,7 @@ import {
   type CodexBundleMcpThreadConfig,
   type EmbeddedRunAttemptParamsV2 as EmbeddedRunAttemptParams,
 } from "openclaw/plugin-sdk/agent-harness-runtime";
+import { createPluginRuntimeMock } from "openclaw/plugin-sdk/plugin-test-runtime";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { startCodexAttemptThread } from "./attempt-startup.js";
 import { isCodexAppServerStartupError } from "./attempt-timeouts.js";
@@ -22,6 +23,7 @@ import {
 import { createCodexTestHostCapabilities } from "./host-capability.test-support.js";
 import { defaultCodexPluginMetadataCache } from "./plugin-metadata-cache.js";
 import { sandboxExecServerRegistry } from "./sandbox-exec-server-registry.js";
+import { releaseCodexSandboxExecServerEnvironment } from "./sandbox-exec-server.js";
 import { createSandboxContext } from "./sandbox-exec-server.test-helpers.js";
 import {
   resetCodexTestBindingStore,
@@ -30,6 +32,7 @@ import {
 import {
   clearSharedCodexAppServerClient,
   clearSharedCodexAppServerClientAndWait,
+  createIsolatedCodexAppServerClient,
   getLeasedSharedCodexAppServerClient,
   releaseLeasedSharedCodexAppServerClient,
   resolveCodexAppServerSpawnIdentity,
@@ -122,6 +125,7 @@ function startThreadWithHarness(
     >[0]["runtimeArtifactRequest"];
     sandbox?: Parameters<typeof startCodexAttemptThread>[0]["sandbox"];
     sandboxExecServerEnabled?: boolean;
+    runtime?: Parameters<typeof startCodexAttemptThread>[0]["runtime"];
   },
 ) {
   const harness = overrides?.harness ?? createClientHarness();
@@ -133,6 +137,7 @@ function startThreadWithHarness(
 
   const run = startCodexAttemptThread({
     bindingStore: testCodexAppServerBindingStore,
+    runtime: overrides?.runtime,
     attemptClientFactory:
       overrides?.attemptClientFactory?.(harness) ?? getLeasedSharedCodexAppServerClient,
     appServer: resolveCodexAppServerRuntimeOptions({ pluginConfig: effectivePluginConfig }),
@@ -229,6 +234,80 @@ async function waitForThreadStart(harness: ClientHarness): Promise<{ id?: number
   return waitForRequest(harness, "thread/start");
 }
 
+function createPairedAttemptRuntime() {
+  const channels: Array<{ close: ReturnType<typeof vi.fn>; sessionId: string }> = [];
+  const openDuplex = vi.fn<
+    NonNullable<Parameters<typeof startCodexAttemptThread>[0]["runtime"]>["nodes"]["openDuplex"]
+  >(async (request) => {
+    let resolveClosed: (value: unknown) => void = () => undefined;
+    const closed = new Promise<unknown>((resolve) => {
+      resolveClosed = resolve;
+    });
+    const channel = {
+      send: vi.fn(async () => undefined),
+      onMessage: vi.fn(() => () => undefined),
+      closed,
+      close: vi.fn(() => resolveClosed({ ok: true })),
+    };
+    channels.push({
+      close: channel.close,
+      sessionId: (request.params as { sessionId: string }).sessionId,
+    });
+    return channel;
+  });
+  return {
+    runtime: createPluginRuntimeMock({ nodes: { openDuplex } }),
+    channels,
+    openDuplex,
+  };
+}
+
+async function startIsolatedPairedAttempt(params: {
+  harness: ClientHarness;
+  sessionId: string;
+  runtime: NonNullable<Parameters<typeof startCodexAttemptThread>[0]["runtime"]>;
+  paths?: AttemptPaths;
+}) {
+  const paths = params.paths ?? createAttemptPaths();
+  const sandbox = {
+    ...createSandboxContext({}),
+    backendId: "node",
+    backend: undefined,
+    fsBridge: undefined,
+    runtimeId: `paired-node-${params.sessionId}`,
+    placementExecutionMode: "remote-exec" as const,
+    placementNodeId: "paired-device-1",
+    placementEnvironmentId: `environment-${params.sessionId}`,
+    placementSessionId: params.sessionId,
+    placementOwnerEpoch: 1,
+  };
+  const run = startThreadWithHarness(5_000, new AbortController().signal, {
+    harness: params.harness,
+    paths,
+    skipStartSpy: true,
+    runtime: params.runtime,
+    sandbox,
+    attemptClientFactory: () => createIsolatedCodexAppServerClient,
+    buildAttemptParams: () => ({
+      ...createAttemptParams(paths),
+      sessionId: params.sessionId,
+      sessionKey: `agent:agent-1:${params.sessionId}`,
+    }),
+  }).run;
+  await answerInitialize(params.harness);
+  const environmentAdd = await waitForRequest(params.harness, "environment/add");
+  params.harness.send({ id: environmentAdd.id, result: {} });
+  const threadStart = await waitForThreadStart(params.harness);
+  params.harness.send({ id: threadStart.id, result: threadStartResult(params.sessionId) });
+  const result = await run;
+  const environmentId = (environmentAdd.params as { environmentId?: string }).environmentId;
+  expect(environmentId).toMatch(/^openclaw-node-/u);
+  expect(
+    readHarnessMessages(params.harness.writes).filter(({ method }) => method === "environment/add"),
+  ).toHaveLength(1);
+  return { result, sandbox, environmentId };
+}
+
 function threadStartResult(threadId = "thread-1") {
   return createThreadStartResult(threadId, "/repo");
 }
@@ -701,6 +780,94 @@ describe("startCodexAttemptThread", () => {
     expect(harness.stdinDestroyed).toBe(true);
   });
 
+  it("retires each fresh paired-node app-server and its registered environment", async () => {
+    const runtime = createPairedAttemptRuntime();
+    const clients = [createClientHarness(), createClientHarness(), createClientHarness()];
+    const start = vi.spyOn(CodexAppServerClient, "start");
+    for (const harness of clients) {
+      start.mockReturnValueOnce(harness.client);
+    }
+    const environmentIds = new Set<string>();
+
+    for (const [index, harness] of clients.entries()) {
+      const attempt = await startIsolatedPairedAttempt({
+        harness,
+        sessionId: `sequential-${index}`,
+        runtime: runtime.runtime,
+      });
+      environmentIds.add(attempt.environmentId!);
+      await releaseCodexSandboxExecServerEnvironment(
+        attempt.sandbox,
+        attempt.result.sandboxEnvironment,
+      );
+      attempt.result.releaseSharedClientLease();
+
+      expect(harness.process.stdin.destroyed).toBe(true);
+      expect(runtime.channels.every(({ close }) => close.mock.calls.length === 1)).toBe(true);
+      expect(sandboxExecServerRegistry.servers.size).toBe(0);
+    }
+
+    expect(environmentIds.size).toBe(clients.length);
+    expect(start).toHaveBeenCalledTimes(clients.length);
+    expect(runtime.openDuplex).toHaveBeenCalledTimes(clients.length);
+  });
+
+  it("closes each paired-node environment and client without interrupting an overlapping sibling", async () => {
+    const first = createClientHarness();
+    const second = createClientHarness();
+    const runtime = createPairedAttemptRuntime();
+    const firstPaths = createAttemptPaths();
+    const secondPaths = createAttemptPaths();
+    const start = vi.spyOn(CodexAppServerClient, "start").mockImplementation((options) => {
+      const codexHome = options?.env?.CODEX_HOME;
+      if (codexHome?.startsWith(`${firstPaths.agentDir}${path.sep}`)) {
+        return first.client;
+      }
+      if (codexHome?.startsWith(`${secondPaths.agentDir}${path.sep}`)) {
+        return second.client;
+      }
+      throw new Error(`Unexpected isolated Codex home: ${codexHome}`);
+    });
+    const [firstAttempt, secondAttempt] = await Promise.all([
+      startIsolatedPairedAttempt({
+        harness: first,
+        sessionId: "overlap-1",
+        runtime: runtime.runtime,
+        paths: firstPaths,
+      }),
+      startIsolatedPairedAttempt({
+        harness: second,
+        sessionId: "overlap-2",
+        runtime: runtime.runtime,
+        paths: secondPaths,
+      }),
+    ]);
+
+    expect(firstAttempt.result.client).toBe(first.client);
+    expect(secondAttempt.result.client).toBe(second.client);
+    expect(firstAttempt.environmentId).not.toBe(secondAttempt.environmentId);
+    expect(start).toHaveBeenCalledTimes(2);
+    const firstChannel = runtime.channels.find(({ sessionId }) => sessionId === "overlap-1");
+    const secondChannel = runtime.channels.find(({ sessionId }) => sessionId === "overlap-2");
+    await releaseCodexSandboxExecServerEnvironment(
+      firstAttempt.sandbox,
+      firstAttempt.result.sandboxEnvironment,
+    );
+    firstAttempt.result.releaseSharedClientLease();
+    expect(first.process.stdin.destroyed).toBe(true);
+    expect(second.process.stdin.destroyed).toBe(false);
+    expect(firstChannel?.close).toHaveBeenCalledOnce();
+    expect(secondChannel?.close).not.toHaveBeenCalled();
+    await releaseCodexSandboxExecServerEnvironment(
+      secondAttempt.sandbox,
+      secondAttempt.result.sandboxEnvironment,
+    );
+    secondAttempt.result.releaseSharedClientLease();
+    expect(second.process.stdin.destroyed).toBe(true);
+    expect(secondChannel?.close).toHaveBeenCalledOnce();
+    expect(sandboxExecServerRegistry.servers.size).toBe(0);
+  });
+
   it("forwards prepared auth without a legacy profile selector", async () => {
     const preparedAuth = {
       kind: "api-key" as const,
diff --git a/extensions/codex/src/app-server/attempt-startup.ts b/extensions/codex/src/app-server/attempt-startup.ts
index 59856b3eba4a..f6b77b32c1c9 100644
--- a/extensions/codex/src/app-server/attempt-startup.ts
+++ b/extensions/codex/src/app-server/attempt-startup.ts
@@ -11,6 +11,7 @@ import {
   type EmbeddedRunAttemptParamsV2 as EmbeddedRunAttemptParams,
   type resolveSandboxContext,
 } from "openclaw/plugin-sdk/agent-harness-runtime";
+import type { PluginRuntime } from "openclaw/plugin-sdk/plugin-runtime";
 import {
   CODEX_APP_SERVER_UNSUBSCRIBE_TIMEOUT_MS,
   CodexAppServerUnsafeSubscriptionError,
@@ -73,6 +74,7 @@ import type { CodexAppServerBindingStore } from "./session-binding.js";
 import {
   clearSharedCodexAppServerClientIfCurrent,
   clearSharedCodexAppServerClientIfCurrentAndUnclaimed,
+  createIsolatedCodexAppServerClient,
   isCodexAppServerStartSelectionChangedError,
   releaseLeasedSharedCodexAppServerClient,
   retireSharedCodexAppServerClientIfCurrent,
@@ -131,6 +133,7 @@ type StartCodexAttemptThreadResult = {
 export async function startCodexAttemptThread(params: {
   attemptClientFactory: CodexAppServerClientFactory;
   bindingStore: CodexAppServerBindingStore;
+  runtime?: PluginRuntime;
   appServer: CodexAppServerRuntimeOptions;
   pluginConfig: CodexPluginConfig;
   computerUseConfig: ResolvedCodexComputerUseConfig;
@@ -171,6 +174,7 @@ export async function startCodexAttemptThread(params: {
   startupTimeoutMs: number;
   signal: AbortSignal;
   onStartupTimeout: () => void | Promise<void>;
+  onExecutionDisconnect?: (error: Error) => void;
   spawnedBy: EmbeddedRunAttemptParams["spawnedBy"];
 }): Promise<StartCodexAttemptThreadResult> {
   let pluginAppServer = params.appServer;
@@ -274,7 +278,11 @@ export async function startCodexAttemptThread(params: {
                 return;
               }
               startupClientLeaseReleased = true;
-              releaseLeasedSharedCodexAppServerClient(activeStartupClient);
+              if (params.attemptClientFactory === createIsolatedCodexAppServerClient) {
+                activeStartupClient.close();
+              } else {
+                releaseLeasedSharedCodexAppServerClient(activeStartupClient);
+              }
             };
             releaseSharedClientLease = startupClientLease;
             attemptedClient = activeStartupClient;
@@ -362,7 +370,10 @@ export async function startCodexAttemptThread(params: {
             const releaseStartupSandboxEnvironment = async () => {
               if (startupSandboxEnvironmentAcquired) {
                 startupSandboxEnvironmentAcquired = false;
-                await releaseCodexSandboxExecServerEnvironment(params.sandbox);
+                await releaseCodexSandboxExecServerEnvironment(
+                  params.sandbox,
+                  startupSandboxEnvironment,
+                );
               }
             };
             releaseStartupResourcesOnTimeout = releaseStartupSandboxEnvironment;
@@ -376,9 +387,11 @@ export async function startCodexAttemptThread(params: {
                 ? await ensureCodexSandboxExecServerEnvironment({
                     client: activeStartupClient,
                     sandbox: params.sandbox ?? null,
+                    runtime: params.runtime,
                     appServerStartOptions: params.appServer.start,
                     timeoutMs: params.appServer.requestTimeoutMs,
-                    signal: startupAbandonController.signal,
+                    signal: AbortSignal.any([params.signal, startupAbandonController.signal]),
+                    onExecutionDisconnect: params.onExecutionDisconnect,
                   })
                 : undefined;
               startupSandboxEnvironmentAcquired = Boolean(startupSandboxEnvironment);
diff --git a/extensions/codex/src/app-server/config-parsing.ts b/extensions/codex/src/app-server/config-parsing.ts
index 6dbae5713641..fbd5d3e6deee 100644
--- a/extensions/codex/src/app-server/config-parsing.ts
+++ b/extensions/codex/src/app-server/config-parsing.ts
@@ -225,6 +225,17 @@ export function isCodexRemoteExecPlacementSandbox(sandbox: unknown): boolean {
   );
 }
 
+export function isCodexPairedNodeRemoteExecPlacementSandbox(sandbox: unknown): boolean {
+  return (
+    isCodexRemoteExecPlacementSandbox(sandbox) &&
+    typeof sandbox === "object" &&
+    sandbox !== null &&
+    "placementNodeId" in sandbox &&
+    typeof sandbox.placementNodeId === "string" &&
+    sandbox.placementNodeId.length > 0
+  );
+}
+
 export function assertCodexAppServerCommandHasNoInlineArgs(params: {
   command: string;
   source: CodexAppServerCommandSource;
diff --git a/extensions/codex/src/app-server/config.ts b/extensions/codex/src/app-server/config.ts
index 370a53ab5ffc..95245e05dfc5 100644
--- a/extensions/codex/src/app-server/config.ts
+++ b/extensions/codex/src/app-server/config.ts
@@ -24,6 +24,7 @@ export type {
 } from "./config-contracts.js";
 export { resolveOpenClawExecPolicyForCodexAppServer } from "./config-exec-policy.js";
 export {
+  isCodexPairedNodeRemoteExecPlacementSandbox,
   isCodexRemoteExecPlacementSandbox,
   isCodexSandboxExecServerEnabled,
   readCodexPluginConfig,
diff --git a/extensions/codex/src/app-server/dynamic-tool-build.test.ts b/extensions/codex/src/app-server/dynamic-tool-build.test.ts
index 38e9dce3ef86..af44a2a26340 100644
--- a/extensions/codex/src/app-server/dynamic-tool-build.test.ts
+++ b/extensions/codex/src/app-server/dynamic-tool-build.test.ts
@@ -225,6 +225,69 @@ describe("Codex app-server dynamic tool build", () => {
     expect(tools).toEqual([]);
   });
 
+  it("keeps host and plugin tools while native paired-device execution owns filesystem and shell", async () => {
+    const workspaceDir = path.join(tempDir, "paired-node-workspace");
+    const params = createParams(path.join(tempDir, "paired-node-session.jsonl"), workspaceDir);
+    params.disableTools = false;
+    params.runtimePlan = createCodexRuntimePlanFixture();
+    const factory = vi.fn((options: Parameters<typeof createOpenClawCodingTools>[0]) => [
+      ...createOpenClawCodingTools(options).filter((tool) => tool.name === "message"),
+      createRuntimeDynamicTool("paired_host_plugin"),
+    ]);
+    setOpenClawCodingToolsFactoryForTests(factory);
+
+    const tools = await buildDynamicToolsForTest(params, workspaceDir, {
+      sandbox: {
+        enabled: true,
+        backendId: "node",
+        workspaceDir,
+        agentWorkspaceDir: workspaceDir,
+        containerWorkdir: "/remote/workspace",
+        workspaceAccess: "rw",
+        browserAllowHostControl: false,
+        placementExecutionMode: "remote-exec",
+        placementNodeId: "paired-device-1",
+      } as never,
+    });
+
+    expect(tools.map((tool) => tool.name)).toEqual(
+      expect.arrayContaining(["message", "paired_host_plugin"]),
+    );
+    expect(factory).toHaveBeenCalledWith(
+      expect.objectContaining({
+        toolConstructionPlan: {
+          includeBaseCodingTools: false,
+          includeShellTools: false,
+          includeChannelTools: true,
+          includeOpenClawTools: true,
+          includePluginTools: true,
+        },
+      }),
+    );
+  });
+
+  it("fails paired-device execution visibly when native execution is unavailable", async () => {
+    const workspaceDir = path.join(tempDir, "paired-node-workspace");
+    const params = createParams(path.join(tempDir, "paired-node-session.jsonl"), workspaceDir);
+    params.disableTools = false;
+    params.runtimePlan = createCodexRuntimePlanFixture();
+    const factory = vi.fn(() => [createRuntimeDynamicTool("exec")]);
+    setOpenClawCodingToolsFactoryForTests(factory);
+
+    await expect(
+      buildDynamicToolsForTest(params, workspaceDir, {
+        sandbox: {
+          enabled: true,
+          backendId: "node",
+          placementExecutionMode: "remote-exec",
+          placementNodeId: "paired-device-1",
+        } as never,
+        nativeToolSurfaceEnabled: false,
+      }),
+    ).rejects.toThrow("requires its native exec-server tool surface");
+    expect(factory).not.toHaveBeenCalled();
+  });
+
   it("uses the prepared explicit-policy fact to disable the native surface", () => {
     const params = createParams("/tmp/session.jsonl", "/tmp/workspace");
     params.disableTools = false;
@@ -2444,6 +2507,20 @@ describe("Codex app-server dynamic tool build", () => {
       }),
     ).toBe(true);
 
+    expect(
+      shouldEnableCodexAppServerNativeToolSurface(
+        params,
+        {
+          ...sandbox,
+          backendId: "node",
+          backend: undefined,
+          placementExecutionMode: "remote-exec",
+          placementNodeId: "device-1",
+        } as never,
+        { sandboxExecServerEnabled: true },
+      ),
+    ).toBe(true);
+
     expect(
       shouldEnableCodexAppServerNativeToolSurface(
         params,
diff --git a/extensions/codex/src/app-server/dynamic-tool-build.ts b/extensions/codex/src/app-server/dynamic-tool-build.ts
index 2a22a97dd67f..4511df38f4da 100644
--- a/extensions/codex/src/app-server/dynamic-tool-build.ts
+++ b/extensions/codex/src/app-server/dynamic-tool-build.ts
@@ -74,6 +74,35 @@ const CODEX_NATIVE_SANDBOX_TOOL_REQUIREMENTS = [
   "apply_patch",
 ] as const;
 const CODEX_MEMORY_FLUSH_DYNAMIC_TOOL_ALLOW = new Set(["read", "write"]);
+
+/** Keeps paired-device filesystem and process ownership on its native exec-server. */
+export function resolveCodexNodePlacementToolConstructionPlan(
+  sandbox: OpenClawSandboxContext | undefined,
+  nativeToolSurfaceEnabled: boolean | undefined,
+): OpenClawCodingToolsOptions["toolConstructionPlan"] {
+  if (
+    !isCodexRemoteExecPlacementSandbox(sandbox) ||
+    sandbox?.backendId !== "node" ||
+    !("placementNodeId" in sandbox) ||
+    typeof sandbox.placementNodeId !== "string" ||
+    !sandbox.placementNodeId
+  ) {
+    return undefined;
+  }
+  if (!nativeToolSurfaceEnabled) {
+    throw new Error(
+      "Codex paired-device remote execution requires its native exec-server tool surface; adjust the session tool policy and start a fresh attempt.",
+    );
+  }
+  return {
+    includeBaseCodingTools: false,
+    includeShellTools: false,
+    includeChannelTools: true,
+    includeOpenClawTools: true,
+    includePluginTools: true,
+  };
+}
+
 function preserveRingZeroSystemAgentTool<T extends { name: string; catalogMode?: string }>(
   allTools: T[],
   filteredTools: T[],
@@ -254,6 +283,10 @@ export async function buildDynamicTools(input: DynamicToolBuildParams) {
   });
   const webFetchHostnameAllowlistRef: { value?: string[] } = {};
   const buildOpenClawCodingTools = () => {
+    const toolConstructionPlan = resolveCodexNodePlacementToolConstructionPlan(
+      input.sandbox,
+      input.nativeToolSurfaceEnabled,
+    );
     const options: OpenClawCodingToolsOptions = {
       agentId: input.sessionAgentId,
       ...buildEmbeddedAttemptToolRunContext(params),
@@ -268,6 +301,7 @@ export async function buildDynamicTools(input: DynamicToolBuildParams) {
           ? { mode: params.permissionMode, root: params.sessionRoot }
           : undefined,
       sandbox: input.sandbox,
+      ...(toolConstructionPlan ? { toolConstructionPlan } : {}),
       messageProvider: resolveCodexMessageToolProvider(params),
       toolPolicyMessageProvider: params.messageProvider ?? params.messageChannel,
       // Capability-gated tools (requiredClientCaps) need the originating client's
@@ -688,7 +722,7 @@ function canCodexAppServerNativeToolSurfaceHonorSandbox(
   }
   if (
     options.sandboxExecServerEnabled === true &&
-    sandbox.backend &&
+    (sandbox.backend || isCodexRemoteExecPlacementSandbox(sandbox)) &&
     canSandboxToolPolicyExposeCodexNativeToolSurface(sandbox)
   ) {
     return true;
diff --git a/extensions/codex/src/app-server/run-attempt-connection.test.ts b/extensions/codex/src/app-server/run-attempt-connection.test.ts
index 38bc0d8ff50d..f36502fadcd7 100644
--- a/extensions/codex/src/app-server/run-attempt-connection.test.ts
+++ b/extensions/codex/src/app-server/run-attempt-connection.test.ts
@@ -19,6 +19,10 @@ import {
   testCodexAppServerBindingStore,
   writeCodexAppServerBinding,
 } from "./session-binding.test-helpers.js";
+import {
+  createIsolatedCodexAppServerClient,
+  getLeasedSharedCodexAppServerClient,
+} from "./shared-client.js";
 
 setupRunAttemptTestHooks();
 
@@ -154,6 +158,69 @@ describe("prepareCodexAttemptConnection", () => {
     expect(connection.disableLoginShell).toBe(true);
   });
 
+  it.each([
+    {
+      name: "paired-device remote execution",
+      placement: { placementExecutionMode: "remote-exec", placementNodeId: "paired-device-1" },
+      expectedFactory: createIsolatedCodexAppServerClient,
+    },
+    {
+      name: "SSH remote execution",
+      placement: { placementExecutionMode: "remote-exec" },
+      expectedFactory: getLeasedSharedCodexAppServerClient,
+    },
+    {
+      name: "local sandbox execution",
+      placement: {},
+      expectedFactory: getLeasedSharedCodexAppServerClient,
+    },
+  ])(
+    "selects the correct app-server ownership for $name",
+    async ({ placement, expectedFactory }) => {
+      const sessionFile = path.join(
+        tempDir,
+        `client-ownership-${placement.placementNodeId ?? "other"}.jsonl`,
+      );
+      const workspaceDir = path.join(
+        tempDir,
+        `workspace-client-ownership-${placement.placementNodeId ?? "other"}`,
+      );
+      const params = createParams(sessionFile, workspaceDir);
+      params.sandbox = { ...createSandboxContext({}), ...placement } as NonNullable<
+        typeof params.sandbox
+      >;
+      if (placement.placementExecutionMode === "remote-exec") {
+        const runtimePlan = createCodexRuntimePlanFixture();
+        params.runtimePlan = {
+          ...runtimePlan,
+          auth: {
+            ...runtimePlan.auth,
+            providerForAuth: "openai",
+            authProfileProviderForAuth: "openai",
+            selectedAuthMode: "api-key",
+            modelRoute: {
+              provider: "openai",
+              modelId: "gpt-5.4-codex",
+              api: "openai-responses",
+              baseUrl: "https://api.openai.com/v1",
+              authRequirement: "api-key",
+              requestTransportOverrides: "none",
+            },
+          },
+        };
+        params.resolvedApiKey = "prepared-test-key";
+      }
+      registerCodexTestSessionIdentity(sessionFile, params.sessionId, params.sessionKey);
+
+      const connection = await prepareCodexAttemptConnection({
+        params,
+        options: { bindingStore: testCodexAppServerBindingStore },
+      });
+
+      expect(connection.attemptClientFactory).toBe(expectedFactory);
+    },
+  );
+
   it("keeps a user-home subscription on native account verification", async () => {
     const sessionFile = path.join(tempDir, "user-home-native-auth.jsonl");
     const workspaceDir = path.join(tempDir, "workspace-user-home-native-auth");
diff --git a/extensions/codex/src/app-server/run-attempt-connection.ts b/extensions/codex/src/app-server/run-attempt-connection.ts
index b0722aaee71c..fd53e8506d62 100644
--- a/extensions/codex/src/app-server/run-attempt-connection.ts
+++ b/extensions/codex/src/app-server/run-attempt-connection.ts
@@ -21,6 +21,7 @@ import {
 import { resolveCodexBindingAppServerConnection } from "./binding-connection.js";
 import {
   canUseCodexModelBackedApprovalsReviewerForModel,
+  isCodexPairedNodeRemoteExecPlacementSandbox,
   isCodexRemoteExecPlacementSandbox,
   readCodexPluginConfig,
   readCodexRequirementsToml,
@@ -47,7 +48,10 @@ import {
   applyCodexSessionPermissionPolicy,
   resolveCodexSessionPermissionCwd,
 } from "./session-permission-policy.js";
-import { getLeasedSharedCodexAppServerClient } from "./shared-client.js";
+import {
+  createIsolatedCodexAppServerClient,
+  getLeasedSharedCodexAppServerClient,
+} from "./shared-client.js";
 import { rotateOversizedCodexAppServerStartupBinding } from "./startup-binding.js";
 
 export async function prepareCodexAttemptConnection({ params, options }: CodexRunAttemptInput) {
@@ -69,7 +73,6 @@ export async function prepareCodexAttemptConnection({ params, options }: CodexRu
   const preDynamicStartupStages = createCodexDynamicToolBuildStageTracker({
     enabled: profilerEnabled,
   });
-  const attemptClientFactory = options.clientFactory ?? getLeasedSharedCodexAppServerClient;
   const runtimeArtifactRequest =
     params.captureRuntimeArtifact || params.expectedRuntimeArtifact
       ? params.expectedRuntimeArtifact
@@ -99,6 +102,12 @@ export async function prepareCodexAttemptConnection({ params, options }: CodexRu
           sessionKey: sandboxSessionKey,
           workspaceDir: resolvedWorkspace,
         });
+  // Upstream cannot remove registered environments, so node leases own one disposable client.
+  const attemptClientFactory =
+    options.clientFactory ??
+    (isCodexPairedNodeRemoteExecPlacementSandbox(sandbox)
+      ? createIsolatedCodexAppServerClient
+      : getLeasedSharedCodexAppServerClient);
   preDynamicStartupStages.mark("sandbox");
   const execPolicy = resolveOpenClawExecPolicyForCodexAppServer({
     // Explicit modes replace legacy fields; full also replaces approval-file floors.
diff --git a/extensions/codex/src/app-server/run-attempt-finalize.ts b/extensions/codex/src/app-server/run-attempt-finalize.ts
index 87fb45abc986..9cc85b6a14b4 100644
--- a/extensions/codex/src/app-server/run-attempt-finalize.ts
+++ b/extensions/codex/src/app-server/run-attempt-finalize.ts
@@ -137,15 +137,21 @@ export async function finalizeCodexAttempt(
   const effectiveTimedOut = state.timedOut && !recoveredTurnWatchTimeout;
   const effectiveTurnCompletionIdleTimedOut =
     state.turnCompletionIdleTimedOut && !recoveredTurnWatchTimeout;
+  // Transport loss aborts in-flight work mechanically, but its terminal outcome
+  // must remain a failure unless the operator explicitly canceled the attempt.
   const isFinalAborted = () =>
-    projectedTerminal.aborted ||
     terminalState.explicitCancellationObserved ||
-    (runAbortController.signal.aborted && !state.clientClosedAbort && !recoveredTurnWatchTimeout);
+    (!resourceState.executionDisconnectError &&
+      (projectedTerminal.aborted ||
+        (runAbortController.signal.aborted &&
+          !state.clientClosedAbort &&
+          !recoveredTurnWatchTimeout)));
   const clientClosedPromptErrorForFinal =
     state.clientClosedPromptError && hasRecoverableCompletedAssistant
       ? undefined
       : state.clientClosedPromptError;
   let finalPromptError =
+    resourceState.executionDisconnectError ??
     clientClosedPromptErrorForFinal ??
     (effectiveTurnCompletionIdleTimedOut
       ? state.turnCompletionIdleTimeoutMessage
@@ -213,6 +219,9 @@ export async function finalizeCodexAttempt(
       rateLimits: readRecentCodexRateLimits(resourceState.client),
     });
   }
+  // Device loss can arrive during asynchronous failure enrichment. Re-read its
+  // owner before freezing derived success, cancellation, and terminal state.
+  finalPromptError = resourceState.executionDisconnectError ?? finalPromptError;
   const finalPromptErrorSource =
     effectiveTimedOut || clientClosedPromptErrorForFinal
       ? "prompt"
diff --git a/extensions/codex/src/app-server/run-attempt-resources.ts b/extensions/codex/src/app-server/run-attempt-resources.ts
index 4a7d9194beae..f22dd9b86a1d 100644
--- a/extensions/codex/src/app-server/run-attempt-resources.ts
+++ b/extensions/codex/src/app-server/run-attempt-resources.ts
@@ -21,10 +21,14 @@ import {
 import { codexNativeSubagentMonitorRuntime } from "./native-subagent-monitor.js";
 import type { CodexSandboxPolicy, CodexTurnEnvironmentParams } from "./protocol.js";
 import type { CodexAttemptPrompt } from "./run-attempt-prompt.js";
-import { releaseCodexSandboxExecServerEnvironment } from "./sandbox-exec-server.js";
+import {
+  releaseCodexSandboxExecServerEnvironment,
+  type CodexSandboxExecEnvironment,
+} from "./sandbox-exec-server.js";
 import type { CodexAppServerThreadBinding } from "./session-binding.js";
 import {
   clearSharedCodexAppServerClientIfCurrentAndUnclaimed,
+  createIsolatedCodexAppServerClient,
   retainSharedCodexAppServerClientIfCurrent,
 } from "./shared-client.js";
 import type { CodexAppServerThreadLifecycleBinding } from "./thread-lifecycle.js";
@@ -55,6 +59,13 @@ export function prepareCodexAttemptResources(prompt: CodexAttemptPrompt) {
     trajectory: params.hostCapabilities.trajectory,
     tools: toolBridge.availableSpecs,
   });
+  const executionState: {
+    sandboxExecEnvironment: CodexSandboxExecEnvironment | undefined;
+    executionDisconnectError: Error | undefined;
+  } = {
+    sandboxExecEnvironment: undefined,
+    executionDisconnectError: undefined,
+  };
   const state = {
     client: undefined as unknown as CodexAppServerClient,
     thread: undefined as unknown as CodexAppServerThreadLifecycleBinding,
@@ -76,7 +87,7 @@ export function prepareCodexAttemptResources(prompt: CodexAttemptPrompt) {
     releaseSharedClientLease: undefined as (() => void) | undefined,
     startupClientUnsafe: false,
     sharedCodexClientRetiredForOneShotCleanup: false,
-    sandboxExecEnvironmentAcquired: false,
+    ...executionState,
     codexEnvironmentSelection: undefined as CodexTurnEnvironmentParams[] | undefined,
     codexExecutionCwd: effectiveCwd,
     codexSandboxPolicy: undefined as CodexSandboxPolicy | undefined,
@@ -148,16 +159,25 @@ export function prepareCodexAttemptResources(prompt: CodexAttemptPrompt) {
       await state.client.closeAndWait({ exitTimeoutMs: 2_000, forceKillDelayMs: 250 });
     }
   };
+  const releaseSandboxExecEnvironment = async () => {
+    if (state.sandboxExecEnvironment) {
+      const environment = state.sandboxExecEnvironment;
+      state.sandboxExecEnvironment = undefined;
+      await releaseCodexSandboxExecServerEnvironment(sandbox, environment);
+    }
+  };
   const releaseSharedClientLeaseAndRetireOneShotClient = async () => {
+    if (connection.attemptClientFactory === createIsolatedCodexAppServerClient) {
+      // Close the authorized node lease first; losing its socket first is a real disconnect.
+      await releaseSandboxExecEnvironment();
+      const ownedClient = state.releaseSharedClientLease ? state.client : undefined;
+      releaseSharedClientLeaseOnce();
+      await ownedClient?.closeAndWait({ exitTimeoutMs: 2_000, forceKillDelayMs: 250 });
+      return;
+    }
     releaseSharedClientLeaseOnce();
     await retireSharedCodexClientForOneShotCleanup();
   };
-  const releaseSandboxExecEnvironment = async () => {
-    if (state.sandboxExecEnvironmentAcquired) {
-      state.sandboxExecEnvironmentAcquired = false;
-      await releaseCodexSandboxExecServerEnvironment(sandbox);
-    }
-  };
   const runCleanupStep = (step: string, operation: () => Promise<void> | void | undefined) =>
     runAgentCleanupStep({
       runId: params.runId,
diff --git a/extensions/codex/src/app-server/run-attempt-start.ts b/extensions/codex/src/app-server/run-attempt-start.ts
index 8523babd2825..aeff465e51e1 100644
--- a/extensions/codex/src/app-server/run-attempt-start.ts
+++ b/extensions/codex/src/app-server/run-attempt-start.ts
@@ -82,6 +82,7 @@ export async function startCodexAttemptRuntime(resources: CodexAttemptResources)
     const startupResult = await startCodexAttemptThread({
       attemptClientFactory,
       bindingStore,
+      runtime: connection.options.runtime,
       appServer: pluginAppServer,
       pluginConfig,
       computerUseConfig,
@@ -119,6 +120,11 @@ export async function startCodexAttemptRuntime(resources: CodexAttemptResources)
       startupTimeoutMs,
       signal: runAbortController.signal,
       onStartupTimeout: () => runAbortController.abort("codex_startup_timeout"),
+      onExecutionDisconnect: (error) => {
+        state.executionDisconnectError = error;
+        embeddedAgentLog.warn(error.message);
+        runAbortController.abort("client_closed");
+      },
       spawnedBy: params.spawnedBy,
     });
     state.client = startupResult.client;
@@ -127,7 +133,7 @@ export async function startCodexAttemptRuntime(resources: CodexAttemptResources)
     state.turnRouter = startupResult.turnRouter;
     state.turnRoute = startupResult.turnRoute;
     // Adopt cleanup ownership before any fallible validation of the started thread.
-    state.sandboxExecEnvironmentAcquired = Boolean(startupResult.sandboxEnvironment);
+    state.sandboxExecEnvironment = startupResult.sandboxEnvironment;
     state.releaseSharedClientLease = startupResult.releaseSharedClientLease;
     state.restartContextEngineCodexThread = startupResult.restartContextEngineCodexThread;
     pluginAppServer = startupResult.pluginAppServer;
@@ -232,6 +238,6 @@ export async function startCodexAttemptRuntime(resources: CodexAttemptResources)
     await runCleanupStep("codex-start-failure-abort-listener", () =>
       params.abortSignal?.removeEventListener("abort", abortFromUpstream),
     );
-    throw error;
+    throw state.executionDisconnectError ?? error;
   }
 }
diff --git a/extensions/codex/src/app-server/run-attempt-types.ts b/extensions/codex/src/app-server/run-attempt-types.ts
index 4393d3c3089e..9d2a071c6e3a 100644
--- a/extensions/codex/src/app-server/run-attempt-types.ts
+++ b/extensions/codex/src/app-server/run-attempt-types.ts
@@ -2,11 +2,13 @@ import type {
   EmbeddedRunAttemptParamsV2 as EmbeddedRunAttemptParams,
   NativeHookRelayEvent,
 } from "openclaw/plugin-sdk/agent-harness-runtime";
+import type { PluginRuntime } from "openclaw/plugin-sdk/plugin-runtime";
 import type { CodexAppServerBindingStore } from "./session-binding.js";
 import type { CodexAppServerClientFactory } from "./shared-client.js";
 
 export type CodexRunAttemptOptions = {
   bindingStore: CodexAppServerBindingStore;
+  runtime?: PluginRuntime;
   pluginConfig?: unknown;
   /** Private app-server request identity; public attempt identity remains params.modelId. */
   runtimeModelId?: string;
diff --git a/extensions/codex/src/app-server/run-attempt.ts b/extensions/codex/src/app-server/run-attempt.ts
index 86e1cb1950ee..1d965c2c128f 100644
--- a/extensions/codex/src/app-server/run-attempt.ts
+++ b/extensions/codex/src/app-server/run-attempt.ts
@@ -66,8 +66,9 @@ export async function runCodexAppServerAttempt(
     turnStart.turn,
   );
 
+  let finalizedResult: EmbeddedRunAttemptResult;
   try {
-    return await finalizeCodexAttempt(
+    finalizedResult = await finalizeCodexAttempt(
       resources,
       turnRuntime,
       lifecycle,
@@ -78,4 +79,13 @@ export async function runCodexAppServerAttempt(
   } finally {
     await cleanupCodexAttempt(resources, turnRuntime, lifecycle, turnRequest, activeTurn);
   }
+  // Cleanup retires the execution lease; only then can device loss no longer
+  // race the final result captured during asynchronous terminal processing.
+  if (
+    resources.state.executionDisconnectError &&
+    !connection.terminalState.explicitCancellationObserved
+  ) {
+    throw resources.state.executionDisconnectError;
+  }
+  return finalizedResult;
 }
diff --git a/extensions/codex/src/app-server/sandbox-exec-server-node-relay.test.ts b/extensions/codex/src/app-server/sandbox-exec-server-node-relay.test.ts
new file mode 100644
index 000000000000..f904164b4738
--- /dev/null
+++ b/extensions/codex/src/app-server/sandbox-exec-server-node-relay.test.ts
@@ -0,0 +1,700 @@
+import { once } from "node:events";
+import type { PluginRuntime } from "openclaw/plugin-sdk/plugin-runtime";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { sandboxExecServerRegistry } from "./sandbox-exec-server-registry.js";
+import {
+  ensureCodexSandboxExecServerEnvironment,
+  releaseCodexSandboxExecServerEnvironment,
+} from "./sandbox-exec-server.js";
+import {
+  createClient,
+  createSandboxContext,
+  execServerUrlFromClient,
+  openSocket,
+  waitForSocketClose,
+} from "./sandbox-exec-server.test-helpers.js";
+
+const customLoggingPattern = vi.hoisted(() => ({ value: "" }));
+vi.mock("openclaw/plugin-sdk/logging-core", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("openclaw/plugin-sdk/logging-core")>();
+  return {
+    ...actual,
+    redactToolPayloadText: (text: string) => {
+      const redacted = actual.redactToolPayloadText(text);
+      return customLoggingPattern.value
+        ? redacted.replaceAll(customLoggingPattern.value, "[redacted]")
+        : redacted;
+    },
+  };
+});
+
+const MAX_CODEX_EXEC_SERVER_MESSAGE_BYTES = 64 * 1024 * 1024;
+
+type NodeChannel = Awaited<ReturnType<PluginRuntime["nodes"]["openDuplex"]>>;
+
+function createNodeChannel() {
+  let resolveClosed: (result: unknown) => void = () => {};
+  let rejectClosed: (error: Error) => void = () => {};
+  let receive: ((message: Uint8Array) => void | Promise<void>) | undefined;
+  let channelClosed = false;
+  const closed = new Promise<unknown>((resolve, reject) => {
+    resolveClosed = resolve;
+    rejectClosed = reject;
+  });
+  const channel = {
+    send: vi.fn<NodeChannel["send"]>(async () => {
+      if (channelClosed) {
+        throw new Error("execution channel closed");
+      }
+    }),
+    onMessage: vi.fn<NodeChannel["onMessage"]>((listener) => {
+      receive = listener;
+      return () => {
+        receive = undefined;
+      };
+    }),
+    closed,
+    close: vi.fn<NodeChannel["close"]>(() => {
+      channelClosed = true;
+      resolveClosed({ ok: true });
+    }),
+  } satisfies NodeChannel;
+  return {
+    channel,
+    disconnect: () => resolveClosed({ ok: false, error: "device disconnected" }),
+    fail: (error: Error) => rejectClosed(error),
+    receive: async (message: Uint8Array) => await receive?.(message),
+  };
+}
+
+function createNodeSandbox() {
+  return {
+    ...createSandboxContext({}),
+    backendId: "node",
+    backend: undefined,
+    fsBridge: undefined,
+    placementExecutionMode: "remote-exec" as const,
+    placementNodeId: "paired-device-1",
+    placementEnvironmentId: "environment-paired-device-1",
+    placementSessionId: "session-paired-device-1",
+    placementOwnerEpoch: 7,
+    containerWorkdir: "/remote/managed-workspace",
+  };
+}
+
+function createNodeRuntime(openDuplex: PluginRuntime["nodes"]["openDuplex"]): PluginRuntime {
+  return { nodes: { openDuplex } } as PluginRuntime;
+}
+
+function encodeHttpBody(contentType: string, body: string) {
+  return {
+    headers: [{ name: "Content-Type", value: contentType }],
+    bodyBase64: Buffer.from(body).toString("base64"),
+  };
+}
+
+async function expectPairedNodeHttpCredentialRejection(params: {
+  url?: string;
+  headers?: Array<{ name: string; value: string }>;
+  bodyBase64?: string;
+}): Promise<void> {
+  const transport = createNodeChannel();
+  const sandbox = createNodeSandbox();
+  const client = createClient();
+  const onExecutionDisconnect = vi.fn<(error: Error) => void>();
+  await ensureCodexSandboxExecServerEnvironment({
+    client: client as never,
+    sandbox,
+    runtime: createNodeRuntime(async () => transport.channel),
+    signal: new AbortController().signal,
+    onExecutionDisconnect,
+  });
+  const socket = await openSocket(execServerUrlFromClient(client));
+  let resolveForwarded: () => void = () => {};
+  const forwarded = new Promise<void>((resolve) => {
+    resolveForwarded = resolve;
+  });
+  transport.channel.send.mockImplementation(async () => resolveForwarded());
+  const outcome = Promise.race([
+    once(socket, "message").then(([message]) => ({
+      kind: "rejected" as const,
+      message: JSON.parse(Buffer.from(message as Buffer).toString()) as {
+        id: number;
+        error: { code: number; message: string };
+      },
+    })),
+    forwarded.then(() => ({ kind: "forwarded" as const })),
+  ]);
+
+  socket.send(
+    JSON.stringify({
+      id: 13,
+      method: "http/request",
+      params: {
+        method: "POST",
+        url: "https://example.test",
+        headers: [],
+        ...params,
+        requestId: "request-13",
+      },
+    }),
+  );
+
+  const result = await outcome;
+  expect(result.kind).toBe("rejected");
+  if (result.kind !== "rejected") {
+    return;
+  }
+  expect(result.message.id).toBe(13);
+  expect(result.message.error).toEqual({
+    code: -32602,
+    message: expect.stringMatching(/authenticated remote HTTP.*Gateway.*credential-free/i),
+  });
+  expect(JSON.stringify(result.message)).not.toContain("synthetic-canary");
+  expect(transport.channel.send).not.toHaveBeenCalled();
+  expect(onExecutionDisconnect).not.toHaveBeenCalled();
+}
+
+afterEach(async () => {
+  customLoggingPattern.value = "";
+  await sandboxExecServerRegistry.closeAll();
+});
+
+describe("Codex paired-device exec-server relay", () => {
+  it("authorizes one bounded attempt-owned node channel before registering the local environment", async () => {
+    const transport = createNodeChannel();
+    const openDuplex = vi.fn<PluginRuntime["nodes"]["openDuplex"]>(async () => transport.channel);
+    const sandbox = createNodeSandbox();
+    const client = createClient();
+    const attempt = new AbortController();
+
+    const environment = await ensureCodexSandboxExecServerEnvironment({
+      client: client as never,
+      sandbox,
+      runtime: createNodeRuntime(openDuplex),
+      signal: attempt.signal,
+    });
+
+    expect(environment).toEqual({
+      environmentId: expect.stringMatching(/^openclaw-node-/),
+      cwd: "/remote/managed-workspace",
+    });
+    expect(environment?.environmentId.length).toBeLessThanOrEqual(64);
+    expect(openDuplex).toHaveBeenCalledWith({
+      nodeId: "paired-device-1",
+      command: "codex.exec-server.stdio.v1",
+      params: {
+        cwd: "/remote/managed-workspace",
+        environmentId: "environment-paired-device-1",
+        sessionId: "session-paired-device-1",
+        ownerEpoch: 7,
+        sessionKey: sandbox.sessionKey,
+      },
+      sessionKey: sandbox.sessionKey,
+      timeoutMs: 0,
+      maxMessageBytes: MAX_CODEX_EXEC_SERVER_MESSAGE_BYTES,
+      maxOutstandingDeliveryBytes: MAX_CODEX_EXEC_SERVER_MESSAGE_BYTES + 2 * 1024 * 1024,
+      signal: attempt.signal,
+    });
+    expect(openDuplex.mock.invocationCallOrder[0]).toBeLessThan(
+      client.request.mock.invocationCallOrder[0] ?? Infinity,
+    );
+    expect(execServerUrlFromClient(client)).toMatch(/^ws:\/\/127\.0\.0\.1:\d+\/openclaw-/);
+  });
+
+  it.each([
+    ["missing environment", { placementEnvironmentId: "" }],
+    ["invalid session", { placementSessionId: " session " }],
+    ["negative owner epoch", { placementOwnerEpoch: -1 }],
+    ["zero owner epoch", { placementOwnerEpoch: 0 }],
+    ["missing session key", { sessionKey: "" }],
+  ])(
+    "rejects a node workspace with %s before opening a channel",
+    async (_label, invalidIdentity) => {
+      const sandbox = { ...createNodeSandbox(), ...invalidIdentity };
+      const client = createClient();
+      const openDuplex = vi.fn<PluginRuntime["nodes"]["openDuplex"]>();
+
+      await expect(
+        ensureCodexSandboxExecServerEnvironment({
+          client: client as never,
+          sandbox,
+          runtime: createNodeRuntime(openDuplex),
+          signal: new AbortController().signal,
+        }),
+      ).rejects.toThrow("exact placement workspace identity");
+
+      expect(openDuplex).not.toHaveBeenCalled();
+      expect(client.request).not.toHaveBeenCalled();
+    },
+  );
+
+  it("preserves versionless and reverse JSON-RPC while scrubbing both process environment maps", async () => {
+    const transport = createNodeChannel();
+    const sandbox = createNodeSandbox();
+    const client = createClient();
+    const environment = await ensureCodexSandboxExecServerEnvironment({
+      client: client as never,
+      sandbox,
+      runtime: createNodeRuntime(async () => transport.channel),
+      signal: new AbortController().signal,
+    });
+    const socket = await openSocket(execServerUrlFromClient(client));
+    const initialize = '{"id":1,"method":"initialize","params":{"clientName":"codex"}}';
+    socket.send(initialize);
+    await vi.waitFor(() => expect(transport.channel.send).toHaveBeenCalledTimes(1));
+    expect(Buffer.from(transport.channel.send.mock.calls[0]![0]).toString()).toBe(initialize);
+
+    socket.send(
+      JSON.stringify({
+        id: 2,
+        method: "process/start",
+        params: {
+          env: {
+            OPENAI_API_KEY: "secret-canary", // pragma: allowlist secret
+            GH_TOKEN: "token-canary", // pragma: allowlist secret
+            HTTPS_PROXY: ["https://user", "proxy-canary@proxy.example"].join(":"),
+            SAFE_CANARY: "ordinary-env",
+            URL: "https://x/e",
+          },
+          envPolicy: {
+            inherit: "none",
+            set: {
+              OPENAI_API_KEY: "policy-secret-canary", // pragma: allowlist secret
+              GITHUB_TOKEN: "policy-token-canary", // pragma: allowlist secret
+              DATABASE_URL: ["postgres://user", "database-canary@db.example/app"].join(":"),
+              SAFE_POLICY: "ordinary-policy",
+              U: "https://x/p",
+            },
+          },
+          unknownFutureField: { preserved: true },
+        },
+      }),
+    );
+    await vi.waitFor(() => expect(transport.channel.send).toHaveBeenCalledTimes(2));
+    const forwarded = JSON.parse(
+      Buffer.from(transport.channel.send.mock.calls[1]![0]).toString(),
+    ) as { params: { env: unknown; envPolicy: { set: unknown }; unknownFutureField: unknown } };
+    const { params } = forwarded;
+    expect(params.env).toEqual({ SAFE_CANARY: "ordinary-env", URL: "https://x/e" });
+    expect(params.envPolicy.set).toEqual({ SAFE_POLICY: "ordinary-policy", U: "https://x/p" });
+    expect(params.unknownFutureField).toEqual({ preserved: true });
+
+    const reverseRequest = JSON.stringify({
+      id: 7,
+      method: "network/policyRequest",
+      params: {
+        processId: "policy-proof",
+        request: { protocol: "https_connect", host: "example.test", port: 443 },
+      },
+    });
+    const received = once(socket, "message");
+    await transport.receive(Buffer.from(reverseRequest));
+    const [message] = await received;
+    expect(Buffer.from(message as Buffer).toString()).toBe(reverseRequest);
+    const reverseResponse = '{"id":7,"result":{"decision":{"type":"allow"}}}';
+    socket.send(reverseResponse);
+    await vi.waitFor(() => expect(transport.channel.send).toHaveBeenCalledTimes(3));
+    expect(Buffer.from(transport.channel.send.mock.calls[2]![0]).toString()).toBe(reverseResponse);
+
+    await releaseCodexSandboxExecServerEnvironment(sandbox, environment);
+    expect(transport.channel.close).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    ["bearer authorization", [{ name: "Authorization", value: "Bearer synthetic-canary" }]],
+    ["OAuth authorization", [{ name: "authorization", value: "OAuth synthetic-canary" }]],
+    [
+      "mixed-case proxy authorization",
+      [{ name: "pRoXy-AuThOrIzAtIoN", value: "Bearer synthetic-canary" }],
+    ],
+    ["request cookie", [{ name: "Cookie", value: "session=synthetic-canary" }]],
+    ["API key", [{ name: "X-Api-Key", value: "synthetic-canary" }]],
+    ["Google API key", [{ name: "x-goog-api-key", value: "synthetic-canary" }]],
+    ["Vault token", [{ name: "X-Vault-Token", value: "synthetic-canary" }]],
+    ["Cloudflare JWT assertion", [{ name: "Cf-Access-Jwt-Assertion", value: "synthetic-canary" }]],
+    ["request signature", [{ name: "X-Request-Signature", value: "synthetic-canary" }]],
+    ["one-time passcode", [{ name: "X-Provider-Otp", value: "synthetic-canary" }]],
+    ["plural credentials", [{ name: "X-Provider-Credentials", value: "synthetic-canary" }]],
+    ["mixed-case auth token", [{ name: "X-AuTh-ToKeN", value: "synthetic-canary" }]],
+    ["provider function key", [{ name: "x-functions-key", value: "synthetic-canary" }]],
+    [
+      "credential after repeated safe headers",
+      [
+        { name: "X-Trace", value: "first" },
+        { name: "x-trace", value: "second" },
+        { name: "aUtHoRiZaTiOn", value: "Bearer synthetic-canary" },
+      ],
+    ],
+  ])(
+    "rejects %s before forwarding any credential to the paired device",
+    async (_label, headers) => await expectPairedNodeHttpCredentialRejection({ headers }),
+  );
+
+  it.each([
+    [
+      "URL Basic credentials",
+      {
+        url: (() => {
+          const url = new URL("https://example.test/path");
+          url.username = "user";
+          url.password = "synthetic-canary";
+          return url.toString();
+        })(),
+      },
+    ],
+    ["OAuth URL access token", { url: "https://example.test/path?access_token=synthetic-canary" }],
+    ["session identity", { url: "https://example.test/path?sessionId=synthetic-canary" }],
+    ["matrix session", { url: "https://x/p;jsessionid=synthetic-canary" }],
+    ["matrix case", { url: "https://x/p;JSESSIONID=synthetic-canary" }],
+    ["encoded matrix", { url: "https://x/p%3Bjsessionid%3Dsynthetic-canary" }],
+    ["nested matrix", { url: "https://x/a;region=west/b;session_id=synthetic-canary" }],
+    ["nested fragment MFA", { url: "https://x/#/callback?mfa_code=123456" }],
+    ["direct access-token fragment", { url: "https://x/#access_token=synthetic-canary" }],
+    ["direct ticket fragment", { url: "https://x/#ticket=synthetic-canary" }],
+    ["encoded path MFA", { url: "https://x/callback%3Fmfa_code%3D123456" }],
+    ["nested encoded MFA", { url: "https://x/callback%253Fmfa_code%253D123456" }],
+    ["ticket query", { url: "https://x/?ticket=synthetic-canary" }],
+    ["bearer query", { url: "https://x/?bearer=synthetic-canary" }],
+    ["SAML assertion", { url: "https://example.test/path?SAMLResponse=synthetic-canary" }],
+    ["OAuth device code", { url: "https://example.test/path?device_code=synthetic-canary" }],
+    ["OAuth consumer key", { url: "https://x/?oauth_consumer_key=synthetic-canary" }],
+    ["encoded token", { url: `https://x/?v=${["sk", "live", "x".repeat(30)].join("%255F")}` }],
+    ["encoded nested credential", { url: "https://x/?u%255Bpassword%255D=synthetic-canary" }],
+    [
+      "OAuth form body",
+      {
+        headers: [{ name: "Content-Type", value: "application/x-www-form-urlencoded" }],
+        bodyBase64: Buffer.from(
+          "grant_type=authorization_code&client_secret=synthetic-canary",
+        ).toString("base64"),
+      },
+    ],
+    [
+      "OAuth client assertion form body",
+      encodeHttpBody("application/x-www-form-urlencoded", "client_assertion=synthetic-canary"),
+    ],
+    [
+      "passphrase form body",
+      encodeHttpBody("application/x-www-form-urlencoded", "passphrase=synthetic-canary"),
+    ],
+    ["pwd JSON body", encodeHttpBody("application/json", '{"pwd":"synthetic-canary"}')],
+    ["OAuth PKCE JSON", encodeHttpBody("application/json", '{"code_verifier":"synthetic-canary"}')],
+    [
+      "duplicate escaped JSON",
+      encodeHttpBody(
+        "application/json",
+        '{"client_se\\u0063ret":"synthetic-canary","client_secret":"safe"}',
+      ),
+    ],
+    [
+      "oversized JSON",
+      encodeHttpBody("application/json", `{"safe":"${"x".repeat(1024 * 1024 + 1)}"}`),
+    ],
+    [
+      "oversized body without a declared content type",
+      { bodyBase64: Buffer.from("x".repeat(1024 * 1024 + 1)).toString("base64") },
+    ],
+    [
+      "invalid JSON body",
+      encodeHttpBody("application/json", '{"client_assertion":"synthetic-canary"'),
+    ],
+    [
+      "unsupported XML body",
+      encodeHttpBody("application/xml", "<credential>synthetic-canary</credential>"),
+    ],
+    [
+      "unsupported multipart body",
+      encodeHttpBody(
+        "multipart/form-data; boundary=test",
+        "--test\r\nsynthetic-canary\r\n--test--",
+      ),
+    ],
+    ["unsupported opaque body", { bodyBase64: Buffer.from("synthetic-canary").toString("base64") }],
+    [
+      "XML disguised as plain text",
+      encodeHttpBody("text/plain", "<credential>synthetic-canary</credential>"),
+    ],
+    ["invalid UTF-8 body", { bodyBase64: Buffer.from([0xff, 0xfe]).toString("base64") }],
+    [
+      "canonical Slack webhook URL",
+      {
+        url: new URL(
+          ["services", `T${"1".repeat(10)}`, `B${"2".repeat(10)}`, "x".repeat(25)].join("%252F"),
+          "https://hooks.slack.com/",
+        ).toString(),
+      },
+    ],
+    [
+      "canonical Discord webhook URL",
+      {
+        url: new URL(
+          ["api", "webhooks", "1".repeat(18), "x".repeat(68)].join("/"),
+          "https://discord.com/",
+        ).toString(),
+      },
+    ],
+  ])(
+    "rejects %s before forwarding any credential to the paired device",
+    async (_label, params) => await expectPairedNodeHttpCredentialRejection(params),
+  );
+
+  it("honors operator-configured custom logging patterns in decoded values", async () => {
+    customLoggingPattern.value = "tenant-pattern-canary";
+    await expectPairedNodeHttpCredentialRejection({
+      url: `https://example.test/?safe=${customLoggingPattern.value.replaceAll("-", "%252D")}`,
+    });
+    await expectPairedNodeHttpCredentialRejection(
+      encodeHttpBody(
+        "application/json",
+        '{"safe":"tenant\\u002dpattern\\u002dcanary","safe":"ok"}',
+      ),
+    );
+  });
+
+  it.each([
+    [
+      "JSON nested routing",
+      "application/json",
+      JSON.stringify({ greeting: "hello", token_count: 2, status_code: 200 }),
+      "https://x/stream;region=west#/callback?view=summary",
+    ],
+    ["ordinary plain text", "text/plain", "ordinary body", "https://x/c%3Fv%3Ds"],
+    ["bracketed plain text", "text/plain", "[INFO] deployment completed", "https://x/"],
+    ["large plain text", "text/plain", "x".repeat(1024 * 1024 + 1), "https://x/"],
+  ])("forwards credential-free %s byte-for-byte", async (_label, contentType, body, url) => {
+    const transport = createNodeChannel();
+    const sandbox = createNodeSandbox();
+    const client = createClient();
+    await ensureCodexSandboxExecServerEnvironment({
+      client: client as never,
+      sandbox,
+      runtime: createNodeRuntime(async () => transport.channel),
+      signal: new AbortController().signal,
+    });
+    const socket = await openSocket(execServerUrlFromClient(client));
+    const request = JSON.stringify({
+      id: 14,
+      method: "http/request",
+      params: {
+        method: "POST",
+        url,
+        headers: [
+          { name: "X-Trace", value: "first" },
+          { name: "x-trace", value: "second" },
+          { name: "Content-Type", value: contentType },
+        ],
+        bodyBase64: Buffer.from(body).toString("base64"),
+        redirectPolicy: "follow",
+        requestId: "request-14",
+        streamResponse: true,
+      },
+    });
+
+    socket.send(request);
+
+    await vi.waitFor(() => expect(transport.channel.send).toHaveBeenCalledOnce());
+    expect(Buffer.from(transport.channel.send.mock.calls[0]![0]).toString()).toBe(request);
+  });
+
+  it("rejects replay of a claimed channel and binds simultaneous leases to fresh exact channels", async () => {
+    const channels = [createNodeChannel(), createNodeChannel()];
+    let nextChannel = 0;
+    const openDuplex = vi.fn<PluginRuntime["nodes"]["openDuplex"]>(
+      async () => channels[nextChannel++]!.channel,
+    );
+    const sandbox = createNodeSandbox();
+    const firstClient = createClient();
+    const secondClient = createClient();
+    const firstDisconnected = vi.fn<(error: Error) => void>();
+    const secondDisconnected = vi.fn<(error: Error) => void>();
+    const runtime = createNodeRuntime(openDuplex);
+    const first = await ensureCodexSandboxExecServerEnvironment({
+      client: firstClient as never,
+      sandbox,
+      runtime,
+      signal: new AbortController().signal,
+      onExecutionDisconnect: firstDisconnected,
+    });
+    const second = await ensureCodexSandboxExecServerEnvironment({
+      client: secondClient as never,
+      sandbox,
+      runtime,
+      signal: new AbortController().signal,
+      onExecutionDisconnect: secondDisconnected,
+    });
+    expect(first?.environmentId).not.toBe(second?.environmentId);
+    expect(firstClient.request).toHaveBeenCalledWith(
+      "environment/add",
+      expect.objectContaining({ environmentId: first?.environmentId }),
+      expect.any(Object),
+    );
+    expect(secondClient.request).toHaveBeenCalledWith(
+      "environment/add",
+      expect.objectContaining({ environmentId: second?.environmentId }),
+      expect.any(Object),
+    );
+    const firstSocket = await openSocket(execServerUrlFromClient(firstClient));
+    const secondSocket = await openSocket(execServerUrlFromClient(secondClient));
+    firstSocket.send('{"id":1,"method":"environment/info"}');
+    secondSocket.send('{"id":2,"method":"environment/status"}');
+    await vi.waitFor(() => {
+      expect(channels[0]!.channel.send).toHaveBeenCalledTimes(1);
+      expect(channels[1]!.channel.send).toHaveBeenCalledTimes(1);
+    });
+
+    const replay = await openSocket(execServerUrlFromClient(firstClient));
+    await expect(waitForSocketClose(replay)).resolves.toEqual({ code: 1008 });
+    const firstSocketClosed = waitForSocketClose(firstSocket);
+    await releaseCodexSandboxExecServerEnvironment(sandbox, first);
+    expect(channels[0]!.channel.close).toHaveBeenCalledTimes(1);
+    expect(channels[1]!.channel.close).not.toHaveBeenCalled();
+    await vi.waitFor(() => expect(firstSocket.readyState).toBe(firstSocket.CLOSED));
+    await expect(firstSocketClosed).resolves.toEqual({ code: 1001 });
+    expect(firstDisconnected).not.toHaveBeenCalled();
+    expect(secondDisconnected).not.toHaveBeenCalled();
+    secondSocket.send('{"id":3,"method":"environment/info"}');
+    await vi.waitFor(() => expect(channels[1]!.channel.send).toHaveBeenCalledTimes(2));
+    const secondReply = once(secondSocket, "message");
+    await channels[1]!.receive(Buffer.from('{"id":3,"result":{"ok":true}}'));
+    await expect(secondReply).resolves.toEqual([
+      Buffer.from('{"id":3,"result":{"ok":true}}'),
+      false,
+    ]);
+    const server = await sandboxExecServerRegistry.servers.get(sandbox.runtimeId);
+    expect(server?.cleanupTasks.size).toBe(1);
+    const secondSocketClosed = waitForSocketClose(secondSocket);
+    await releaseCodexSandboxExecServerEnvironment(sandbox, second);
+    expect(channels[1]!.channel.close).toHaveBeenCalledTimes(1);
+    await expect(secondSocketClosed).resolves.toEqual({ code: 1001 });
+    expect(server?.cleanupTasks.size).toBe(0);
+    expect(firstDisconnected).not.toHaveBeenCalled();
+    expect(secondDisconnected).not.toHaveBeenCalled();
+  });
+
+  it("makes a node disconnect terminal and closes its transport exactly once", async () => {
+    const transport = createNodeChannel();
+    const sandbox = createNodeSandbox();
+    const client = createClient();
+    const onExecutionDisconnect = vi.fn<(error: Error) => void>();
+    const environment = await ensureCodexSandboxExecServerEnvironment({
+      client: client as never,
+      sandbox,
+      runtime: createNodeRuntime(async () => transport.channel),
+      signal: new AbortController().signal,
+      onExecutionDisconnect,
+    });
+    const socket = await openSocket(execServerUrlFromClient(client));
+    const socketClosed = waitForSocketClose(socket);
+    transport.disconnect();
+    await expect(socketClosed).resolves.toEqual({ code: 1001 });
+    expect(onExecutionDisconnect).toHaveBeenCalledOnce();
+    expect(onExecutionDisconnect).toHaveBeenCalledWith(
+      expect.objectContaining({ message: expect.stringContaining("start a fresh attempt") }),
+    );
+    await expect(transport.channel.send(Buffer.from("{}"))).rejects.toThrow(
+      "execution channel closed",
+    );
+    await releaseCodexSandboxExecServerEnvironment(sandbox, environment);
+    expect(transport.channel.close).toHaveBeenCalledTimes(1);
+  });
+
+  it("fails an unclaimed node channel immediately before its loopback socket connects", async () => {
+    const transport = createNodeChannel();
+    const sandbox = createNodeSandbox();
+    const client = createClient();
+    const attempt = new AbortController();
+    let rejectRegistration: (error: Error) => void = () => {};
+    const registration = new Promise<Record<string, never>>((_resolve, reject) => {
+      rejectRegistration = reject;
+    });
+    client.request.mockImplementation(async () => await registration);
+    const onExecutionDisconnect = vi.fn((error: Error) => {
+      attempt.abort(error);
+      rejectRegistration(error);
+    });
+    const environment = ensureCodexSandboxExecServerEnvironment({
+      client: client as never,
+      sandbox,
+      runtime: createNodeRuntime(async () => transport.channel),
+      signal: attempt.signal,
+      onExecutionDisconnect,
+    });
+    await vi.waitFor(() => expect(client.request).toHaveBeenCalledOnce());
+    const fakeSecret = "sk-1234567890abcdef";
+
+    transport.fail(new Error(`exec-server exited: OPENAI_API_KEY=${fakeSecret}`));
+
+    await expect(environment).rejects.toThrow("exec-server exited");
+    expect(onExecutionDisconnect).toHaveBeenCalledOnce();
+    expect(onExecutionDisconnect.mock.calls[0]?.[0].message).not.toContain(fakeSecret);
+    expect(transport.channel.close).toHaveBeenCalledTimes(1);
+    expect(sandboxExecServerRegistry.servers.has(sandbox.runtimeId)).toBe(false);
+  });
+
+  it("surfaces bounded node-command failures without exposing credentials", async () => {
+    const transport = createNodeChannel();
+    const sandbox = createNodeSandbox();
+    const client = createClient();
+    const onExecutionDisconnect = vi.fn<(error: Error) => void>();
+    const environment = await ensureCodexSandboxExecServerEnvironment({
+      client: client as never,
+      sandbox,
+      runtime: createNodeRuntime(async () => transport.channel),
+      signal: new AbortController().signal,
+      onExecutionDisconnect,
+    });
+    const socket = await openSocket(execServerUrlFromClient(client));
+    const socketClosed = waitForSocketClose(socket);
+    const fakeSecret = "sk-1234567890abcdef";
+
+    transport.fail(
+      new Error(`exec-server launch failed: OPENAI_API_KEY=${fakeSecret} ${"x".repeat(300)}`),
+    );
+
+    await expect(socketClosed).resolves.toEqual({ code: 1011 });
+    expect(onExecutionDisconnect).toHaveBeenCalledOnce();
+    const failure = onExecutionDisconnect.mock.calls[0]?.[0];
+    expect(failure?.message).toContain("exec-server launch failed");
+    expect(failure?.message).not.toContain(fakeSecret);
+    expect(failure?.message.length).toBeLessThan(360);
+    await releaseCodexSandboxExecServerEnvironment(sandbox, environment);
+    expect(transport.channel.close).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects device frames above the upstream 64 MiB JSON-RPC ceiling", async () => {
+    const transport = createNodeChannel();
+    const sandbox = createNodeSandbox();
+    const client = createClient();
+    await ensureCodexSandboxExecServerEnvironment({
+      client: client as never,
+      sandbox,
+      runtime: createNodeRuntime(async () => transport.channel),
+      signal: new AbortController().signal,
+    });
+    const socket = await openSocket(execServerUrlFromClient(client));
+    const socketClosed = waitForSocketClose(socket);
+    await transport.receive(new Uint8Array(MAX_CODEX_EXEC_SERVER_MESSAGE_BYTES + 1));
+    await expect(socketClosed).resolves.toEqual({ code: 1009 });
+    expect(transport.channel.close).toHaveBeenCalledTimes(1);
+  });
+
+  it("never registers an environment when paired-device authorization is denied", async () => {
+    const sandbox = createNodeSandbox();
+    const client = createClient();
+    const openDuplex = vi.fn<PluginRuntime["nodes"]["openDuplex"]>(async () => {
+      throw new Error("paired-device approval denied");
+    });
+
+    await expect(
+      ensureCodexSandboxExecServerEnvironment({
+        client: client as never,
+        sandbox,
+        runtime: createNodeRuntime(openDuplex),
+        signal: new AbortController().signal,
+      }),
+    ).rejects.toThrow("paired-device approval denied");
+    expect(client.request).not.toHaveBeenCalled();
+    expect(sandboxExecServerRegistry.servers.has(sandbox.runtimeId)).toBe(false);
+  });
+});
diff --git a/extensions/codex/src/app-server/sandbox-exec-server-node-relay.ts b/extensions/codex/src/app-server/sandbox-exec-server-node-relay.ts
new file mode 100644
index 000000000000..a702253fb66e
--- /dev/null
+++ b/extensions/codex/src/app-server/sandbox-exec-server-node-relay.ts
@@ -0,0 +1,509 @@
+import { createDeferred } from "openclaw/plugin-sdk/extension-shared";
+import { redactToolPayloadText } from "openclaw/plugin-sdk/logging-core";
+import { sanitizeEnvVars } from "openclaw/plugin-sdk/sandbox";
+import { formatErrorMessage, redactSensitiveText } from "openclaw/plugin-sdk/security-runtime";
+import { isRecord } from "openclaw/plugin-sdk/string-coerce-runtime";
+import { truncateUtf16Safe } from "openclaw/plugin-sdk/text-utility-runtime";
+import type { RawData, WebSocket } from "ws";
+import type { CodexNodeExecServerLease } from "./sandbox-exec-server/types.js";
+
+const CODEX_NODE_EXEC_SERVER_MAX_MESSAGE_BYTES = 64 * 1024 * 1024;
+const CODEX_NODE_EXEC_SERVER_MAX_FAILURE_DETAIL_CHARS = 240;
+const CODEX_NODE_HTTP_CREDENTIAL_BODY_MAX_BYTES = 1024 * 1024;
+const CODEX_NODE_HTTP_CREDENTIAL_SCAN_MAX_FIELDS = 256;
+const CODEX_NODE_HTTP_CREDENTIAL_SCAN_MAX_DEPTH = 8;
+// Plugin SDK exposes no credential classifiers; mirror canonical names without deep core imports.
+const CODEX_NODE_HTTP_CREDENTIAL_HEADER_NAMES = new Set([
+  "authorization",
+  "proxy-authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "api-key",
+  "apikey",
+  "x-auth-token",
+  "auth-token",
+  "x-access-token",
+  "access-token",
+  "x-secret-key",
+  "secret-key",
+  "x-goog-api-key",
+  "x-vault-token",
+  "x-api-token",
+]);
+const CODEX_NODE_HTTP_CREDENTIAL_HEADER_NAME_PATTERN =
+  /(?:^|[-_])(?:auth(?:orization|entication)?|token|secret|api[-_]?key|apikey|key|password|passwd|pwd|passphrase|passcode|credentials?|session|jwt|assertion|verifier|sig(?:nature)?|hmac|bearer|ticket|challenge|proof|dpop|otp|totp|pin|mfa)(?:[-_]|$)/iu;
+const CODEX_NODE_HTTP_CREDENTIAL_FIELD_NAME_PATTERN =
+  /^(?:(?:[a-z\d]+_)*(?:token|secret|password|passwd|pwd|passphrase|passcode|credentials?|authorization|api_?key|private_key|secret_key|secret_access_key|jwt|assertion|verifier|signature|hmac|bearer|ticket|(?:oauth|consumer|auth|access)_key|otp|totp|pin)|(?:device|authorization|auth|verification|mfa)_code|session(?:_id)?|jsessionid|saml(?:_?response|_?assertion)?|auth|jwt|code|sig|signature|hmac|key|pass)$/u;
+const nodeExecServerTextDecoder = new TextDecoder("utf-8", { fatal: true });
+
+/** Produces the bounded, redacted terminal failure shared by pending and claimed node leases. */
+export function createCodexNodeExecServerDisconnectError(reason: string, cause?: unknown): Error {
+  const detail =
+    cause === undefined
+      ? ""
+      : `: ${truncateUtf16Safe(
+          redactSensitiveText(formatErrorMessage(cause), { mode: "tools" }),
+          CODEX_NODE_EXEC_SERVER_MAX_FAILURE_DETAIL_CHARS,
+        )}`;
+  return new Error(
+    `Codex paired execution device disconnected; start a fresh attempt. (${reason}${detail})`,
+  );
+}
+
+/** Relays one authorized, single-use Codex exec-server channel without interpreting its protocol. */
+export async function startCodexNodeExecServerRelay(params: {
+  lease: CodexNodeExecServerLease;
+  socket: WebSocket;
+}): Promise<void> {
+  const { channel } = params.lease;
+  const { socket } = params;
+  let closed = false;
+  const { promise: finished, resolve: finish } = createDeferred<void>();
+  let unsubscribe = () => {};
+
+  const closeBoth = (code = 1001, reason = "execution channel closed") => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    unsubscribe();
+    params.lease.closeRelay = undefined;
+    params.lease.onChannelClosed = undefined;
+    if (!params.lease.closed) {
+      params.lease.closed = true;
+      channel.close();
+    }
+    if (socket.readyState === socket.OPEN || socket.readyState === socket.CONNECTING) {
+      socket.close(code, reason);
+    }
+    finish();
+  };
+  // The shared loopback server can outlive this lease, so release owns its exact socket.
+  params.lease.closeRelay = closeBoth;
+
+  const failUnexpectedly = (code: number, reason: string, cause?: unknown) => {
+    if (!closed && !params.lease.closed) {
+      params.lease.onDisconnected?.(createCodexNodeExecServerDisconnectError(reason, cause));
+    }
+    closeBoth(code, reason);
+  };
+
+  params.lease.onChannelClosed = ({ failed, error }) =>
+    failUnexpectedly(
+      failed ? 1011 : 1001,
+      failed ? "execution device failed" : "execution device disconnected",
+      error,
+    );
+  socket.once("close", () => failUnexpectedly(1001, "execution socket closed"));
+  socket.once("error", () => failUnexpectedly(1011, "execution socket failed"));
+
+  let toNode = Promise.resolve();
+  socket.on("message", (data: RawData) => {
+    if (closed) {
+      return;
+    }
+    // Stop reading the app-server socket until node-carrier backpressure clears.
+    socket.pause();
+    toNode = toNode
+      .then(async () => {
+        const frame = normalizeCodexExecServerFrame(data);
+        const request = validateCodexExecServerMessage(frame);
+        const rejection = rejectCredentialedCodexNodeHttpRequest(request);
+        if (rejection) {
+          await sendCodexExecServerFrame(socket, rejection);
+        } else {
+          await channel.send(sanitizeCodexExecServerRequest(frame, request));
+        }
+        if (!closed) {
+          socket.resume();
+        }
+      })
+      .catch((error: unknown) => {
+        failUnexpectedly(error instanceof RangeError ? 1009 : 1007, "invalid execution message");
+      });
+  });
+
+  unsubscribe = channel.onMessage(async (message) => {
+    if (closed) {
+      return;
+    }
+    try {
+      const frame = normalizeCodexExecServerFrame(message);
+      validateCodexExecServerMessage(frame);
+      await sendCodexExecServerFrame(socket, frame);
+    } catch (error) {
+      failUnexpectedly(error instanceof RangeError ? 1009 : 1007, "invalid device message");
+    }
+  });
+
+  await finished;
+}
+
+function sendCodexExecServerFrame(socket: WebSocket, frame: Buffer): Promise<void> {
+  return new Promise((resolve, reject) => {
+    socket.send(frame, { binary: false }, (error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+function normalizeCodexExecServerFrame(data: RawData | Uint8Array): Buffer {
+  const frame = Array.isArray(data)
+    ? Buffer.concat(data)
+    : Buffer.isBuffer(data)
+      ? data
+      : data instanceof Uint8Array
+        ? Buffer.from(data.buffer, data.byteOffset, data.byteLength)
+        : Buffer.from(data);
+  if (frame.length > CODEX_NODE_EXEC_SERVER_MAX_MESSAGE_BYTES) {
+    throw new RangeError("Codex exec-server message exceeds its 64 MiB limit.");
+  }
+  if (frame.includes(10) || frame.includes(13)) {
+    throw new Error("Codex exec-server messages must occupy exactly one stdio line.");
+  }
+  return frame;
+}
+
+function validateCodexExecServerMessage(frame: Buffer): Record<string, unknown> {
+  const parsed: unknown = JSON.parse(nodeExecServerTextDecoder.decode(frame));
+  if (!isRecord(parsed)) {
+    throw new Error("Codex exec-server message must be a JSON object.");
+  }
+  return parsed;
+}
+
+function rejectCredentialedCodexNodeHttpRequest(
+  request: Record<string, unknown>,
+): Buffer | undefined {
+  if (request.method !== "http/request") {
+    return undefined;
+  }
+  if (!isRecord(request.params)) {
+    throw new Error("Codex http/request params must be an object.");
+  }
+  const headers = request.params.headers ?? [];
+  if (!Array.isArray(headers)) {
+    throw new Error("Codex http/request headers must be an array.");
+  }
+  if (headers.length > CODEX_NODE_HTTP_CREDENTIAL_SCAN_MAX_FIELDS) {
+    return createCredentialedCodexNodeHttpRejection(request);
+  }
+  let credentialBearing = false;
+  let contentType: string | undefined;
+  for (const header of headers) {
+    if (!isRecord(header) || typeof header.name !== "string" || typeof header.value !== "string") {
+      throw new Error("Codex http/request headers must contain string names and values.");
+    }
+    const name = header.name.trim().toLowerCase();
+    if (
+      CODEX_NODE_HTTP_CREDENTIAL_HEADER_NAMES.has(name) ||
+      CODEX_NODE_HTTP_CREDENTIAL_HEADER_NAME_PATTERN.test(name) ||
+      hasSensitiveCodexNodeText(header.value)
+    ) {
+      credentialBearing = true;
+    }
+    if (name === "content-type") {
+      const declared = header.value.split(";", 1)[0]?.trim().toLowerCase();
+      credentialBearing ||= Boolean(contentType && contentType !== declared);
+      contentType = declared;
+    }
+  }
+  if (!credentialBearing && typeof request.params.url === "string") {
+    credentialBearing = hasCredentialedCodexNodeHttpUrl(request.params.url);
+  }
+  if (!credentialBearing && request.params.bodyBase64 != null) {
+    credentialBearing = hasCredentialedCodexNodeHttpBody(request.params.bodyBase64, contentType);
+  }
+  return credentialBearing ? createCredentialedCodexNodeHttpRejection(request) : undefined;
+}
+
+function hasCredentialedCodexNodeHttpUrl(value: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Codex http/request URL must be valid.");
+  }
+  if (url.username || url.password || hasSensitiveCodexNodeText(value)) {
+    return true;
+  }
+  let fields = 0;
+  const hasCredentialedParameter = (name: string, parameterValue: string): boolean =>
+    ++fields > CODEX_NODE_HTTP_CREDENTIAL_SCAN_MAX_FIELDS ||
+    isCodexNodeCredentialField(name) ||
+    hasSensitiveCodexNodeText(parameterValue);
+  for (const parameters of [url.searchParams, new URLSearchParams(url.hash.slice(1))]) {
+    for (const [name, parameterValue] of parameters) {
+      if (hasCredentialedParameter(name, parameterValue)) {
+        return true;
+      }
+    }
+  }
+  for (const initial of [url.pathname, url.hash.slice(1), ...url.searchParams.values()]) {
+    let component = initial;
+    for (let depth = 0; depth <= CODEX_NODE_HTTP_CREDENTIAL_SCAN_MAX_DEPTH; depth += 1) {
+      for (const nestedQuery of component.split(/[?#]/u).slice(1)) {
+        for (const [name, parameterValue] of new URLSearchParams(nestedQuery)) {
+          if (hasCredentialedParameter(name, parameterValue)) {
+            return true;
+          }
+        }
+      }
+      for (const segment of component.split("/")) {
+        for (const parameter of segment.split(";").slice(1)) {
+          const separator = parameter.indexOf("=");
+          const name = separator < 0 ? parameter : parameter.slice(0, separator);
+          const parameterValue = separator < 0 ? "" : parameter.slice(separator + 1);
+          if (hasCredentialedParameter(name, parameterValue)) {
+            return true;
+          }
+        }
+      }
+      if (!/%[\da-f]{2}/iu.test(component)) {
+        break;
+      }
+      if (depth === CODEX_NODE_HTTP_CREDENTIAL_SCAN_MAX_DEPTH) {
+        return true;
+      }
+      try {
+        component = decodeURIComponent(component);
+      } catch {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function hasCredentialedCodexNodeHttpBody(
+  value: unknown,
+  contentType: string | undefined,
+): boolean {
+  if (typeof value !== "string") {
+    throw new Error("Codex http/request bodyBase64 must be a string.");
+  }
+  const declaredText = contentType === "text/plain";
+  if (
+    !declaredText &&
+    value.length > Math.ceil(CODEX_NODE_HTTP_CREDENTIAL_BODY_MAX_BYTES / 3) * 4
+  ) {
+    // Missing content-type or binary disguise must not bypass bounded credential inspection.
+    return true;
+  }
+  let body: string;
+  try {
+    const decoded = Buffer.from(value, "base64");
+    if (
+      (!declaredText && decoded.length > CODEX_NODE_HTTP_CREDENTIAL_BODY_MAX_BYTES) ||
+      decoded.toString("base64") !== value
+    ) {
+      return true;
+    }
+    body = nodeExecServerTextDecoder.decode(decoded);
+  } catch {
+    return true;
+  }
+  if (!body) {
+    return false;
+  }
+  if (hasSensitiveCodexNodeText(body)) {
+    return true;
+  }
+  const declaredJson =
+    contentType === "application/json" || contentType?.endsWith("+json") === true;
+  const declaredForm = contentType === "application/x-www-form-urlencoded";
+  if (contentType && !declaredJson && !declaredForm && !declaredText) {
+    return true;
+  }
+  const trimmed = body.trimStart();
+  if (trimmed.startsWith("<")) {
+    return true;
+  }
+  if (declaredJson || trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      if (hasCredentialedCodexNodeRawJsonStrings(body)) {
+        return true;
+      }
+      const json: unknown = JSON.parse(body);
+      return hasCredentialedCodexNodeJsonFields(json);
+    } catch {
+      if (!declaredText) {
+        return true;
+      }
+    }
+  }
+  if (!declaredForm && !body.includes("=")) {
+    return !declaredText;
+  }
+  let fields = 0;
+  for (const [name, parameterValue] of new URLSearchParams(body)) {
+    if (
+      ++fields > CODEX_NODE_HTTP_CREDENTIAL_SCAN_MAX_FIELDS ||
+      isCodexNodeCredentialField(name) ||
+      hasSensitiveCodexNodeText(parameterValue)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function hasCredentialedCodexNodeRawJsonStrings(body: string): boolean {
+  const tokens = body.matchAll(/("(?:\\.|[^"\\])*")(\s*:)?/gu);
+  let fields = 0;
+  for (const match of tokens) {
+    const value: unknown = JSON.parse(match[1]!);
+    if (
+      ++fields > CODEX_NODE_HTTP_CREDENTIAL_SCAN_MAX_FIELDS ||
+      typeof value !== "string" ||
+      hasSensitiveCodexNodeText(value) ||
+      (match[2] !== undefined && isCodexNodeCredentialField(value))
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function hasCredentialedCodexNodeJsonFields(value: unknown): boolean {
+  const pending = [{ value, depth: 0 }];
+  let fields = 0;
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (typeof current?.value === "string" && hasSensitiveCodexNodeText(current.value)) {
+      return true;
+    }
+    if (!current || (!Array.isArray(current.value) && !isRecord(current.value))) {
+      continue;
+    }
+    if (current.depth >= CODEX_NODE_HTTP_CREDENTIAL_SCAN_MAX_DEPTH) {
+      return true;
+    }
+    const entries = Array.isArray(current.value)
+      ? current.value.map((entry) => [undefined, entry] as const)
+      : Object.entries(current.value);
+    for (const [name, nested] of entries) {
+      if (
+        ++fields > CODEX_NODE_HTTP_CREDENTIAL_SCAN_MAX_FIELDS ||
+        (typeof name === "string" && isCodexNodeCredentialField(name))
+      ) {
+        return true;
+      }
+      pending.push({ value: nested, depth: current.depth + 1 });
+    }
+  }
+  return false;
+}
+
+function hasSensitiveCodexNodeText(value: string): boolean {
+  let decoded = value;
+  for (let depth = 0; depth <= CODEX_NODE_HTTP_CREDENTIAL_SCAN_MAX_DEPTH; depth += 1) {
+    if (redactToolPayloadText(decoded) !== decoded) {
+      return true;
+    }
+    if (!/%[\da-f]{2}/iu.test(decoded)) {
+      return false;
+    }
+    try {
+      decoded = decodeURIComponent(decoded);
+    } catch {
+      return true;
+    }
+  }
+  return true;
+}
+
+function isCodexNodeCredentialField(value: string): boolean {
+  let decoded = value;
+  for (let depth = 0; depth < CODEX_NODE_HTTP_CREDENTIAL_SCAN_MAX_DEPTH; depth += 1) {
+    let next: string;
+    try {
+      next = decodeURIComponent(decoded);
+    } catch {
+      return true;
+    }
+    if (next === decoded) {
+      break;
+    }
+    decoded = next;
+  }
+  const normalized = decoded
+    .replace(/[\p{C}\p{Z}\u115F\u1160\u3164\uFFA0+]/gu, "")
+    .replace(/([a-z\d])([A-Z])/gu, "$1_$2")
+    .replaceAll("-", "_")
+    .toLowerCase();
+  return (
+    normalized.length > CODEX_NODE_HTTP_CREDENTIAL_SCAN_MAX_FIELDS ||
+    normalized
+      .split(/[.[\]]+/u)
+      .some((component) => CODEX_NODE_HTTP_CREDENTIAL_FIELD_NAME_PATTERN.test(component))
+  );
+}
+
+function createCredentialedCodexNodeHttpRejection(request: Record<string, unknown>): Buffer {
+  if (typeof request.id !== "string" && typeof request.id !== "number") {
+    throw new Error("Codex http/request must have a JSON-RPC request id.");
+  }
+  return Buffer.from(
+    JSON.stringify({
+      jsonrpc: "2.0",
+      id: request.id,
+      error: {
+        code: -32602,
+        message:
+          "Authenticated remote HTTP is unavailable on paired devices; run on Gateway or use an intentionally credential-free endpoint.",
+      },
+    }),
+  );
+}
+
+function sanitizeCodexExecServerRequest(frame: Buffer, request: Record<string, unknown>): Buffer {
+  if (request.method !== "process/start") {
+    return frame;
+  }
+  if (!isRecord(request.params)) {
+    throw new Error("Codex process/start params must be an object.");
+  }
+  sanitizeCodexExecServerEnvironment(request.params, "env");
+  if (request.params.envPolicy !== undefined) {
+    if (!isRecord(request.params.envPolicy)) {
+      throw new Error("Codex process/start envPolicy must be an object.");
+    }
+    sanitizeCodexExecServerEnvironment(request.params.envPolicy, "set");
+  }
+  return normalizeCodexExecServerFrame(Buffer.from(JSON.stringify(request)));
+}
+
+function sanitizeCodexExecServerEnvironment(
+  record: Record<string, unknown>,
+  key: "env" | "set",
+): void {
+  const environment = record[key];
+  if (environment === undefined) {
+    return;
+  }
+  if (!isRecord(environment)) {
+    throw new Error(`Codex process/start ${key} must be an object.`);
+  }
+  const values: Record<string, string> = {};
+  for (const [name, value] of Object.entries(environment)) {
+    if (typeof value !== "string") {
+      throw new Error(`Codex process/start ${key} values must be strings.`);
+    }
+    try {
+      const url = new URL(value);
+      if (url.username || url.password) {
+        continue;
+      }
+    } catch {
+      // Ordinary environment values need not be URLs.
+    }
+    values[name] = value;
+  }
+  record[key] = sanitizeEnvVars(values).allowed;
+}
diff --git a/extensions/codex/src/app-server/sandbox-exec-server-registry.ts b/extensions/codex/src/app-server/sandbox-exec-server-registry.ts
index 025fb016157c..87927b2d468a 100644
--- a/extensions/codex/src/app-server/sandbox-exec-server-registry.ts
+++ b/extensions/codex/src/app-server/sandbox-exec-server-registry.ts
@@ -1,12 +1,21 @@
-import type { OpenClawExecServer } from "./sandbox-exec-server/types.js";
+import type { OpenClawLeasedExecServer } from "./sandbox-exec-server/types.js";
 
 export const sandboxExecServerRegistry = {
-  servers: new Map<string, Promise<OpenClawExecServer>>(),
-  async close(server: OpenClawExecServer): Promise<void> {
+  servers: new Map<string, Promise<OpenClawLeasedExecServer>>(),
+  async close(server: OpenClawLeasedExecServer): Promise<void> {
     if (server.closed) {
       return;
     }
     server.closed = true;
+    if ("node" in server) {
+      for (const lease of server.node.leases.values()) {
+        if (!lease.closed) {
+          lease.closed = true;
+          lease.channel.close();
+        }
+      }
+      server.node.leases.clear();
+    }
     for (const client of server.server.clients) {
       client.close(1001, "shutdown");
     }
diff --git a/extensions/codex/src/app-server/sandbox-exec-server.ts b/extensions/codex/src/app-server/sandbox-exec-server.ts
index f0f0c009747f..de2c0ba8f876 100644
--- a/extensions/codex/src/app-server/sandbox-exec-server.ts
+++ b/extensions/codex/src/app-server/sandbox-exec-server.ts
@@ -7,14 +7,25 @@ import { once } from "node:events";
 import type { IncomingMessage } from "node:http";
 import { isIP, type AddressInfo } from "node:net";
 import { embeddedAgentLog } from "openclaw/plugin-sdk/agent-harness-runtime";
+import type { PluginRuntime } from "openclaw/plugin-sdk/plugin-runtime";
 import type { SandboxContext } from "openclaw/plugin-sdk/sandbox";
 import { WebSocketServer, type RawData, type WebSocket } from "ws";
 import type { CodexAppServerClient } from "./client.js";
 import type { CodexAppServerStartOptions } from "./config.js";
+import {
+  createCodexNodeExecServerDisconnectError,
+  startCodexNodeExecServerRelay,
+} from "./sandbox-exec-server-node-relay.js";
 import { sandboxExecServerRegistry } from "./sandbox-exec-server-registry.js";
 import { parseRequest } from "./sandbox-exec-server/json-rpc.js";
+import type { SandboxChildOwner } from "./sandbox-exec-server/sandbox-child.js";
 import { CodexSandboxExecSession } from "./sandbox-exec-server/session.js";
-import type { OpenClawExecServer } from "./sandbox-exec-server/types.js";
+import type {
+  CodexNodeExecServerLease,
+  OpenClawExecServer,
+  OpenClawLeasedExecServer,
+  OpenClawNodeExecServer,
+} from "./sandbox-exec-server/types.js";
 
 /** Codex environment metadata registered for one sandbox exec-server lease. */
 export type CodexSandboxExecEnvironment = {
@@ -23,46 +34,77 @@ export type CodexSandboxExecEnvironment = {
 };
 
 const CODEX_SANDBOX_EXEC_SERVER_MAX_INBOUND_MESSAGE_BYTES = 100 * 1024 * 1024;
+const CODEX_NODE_EXEC_SERVER_MAX_MESSAGE_BYTES = 64 * 1024 * 1024;
+const codexNodeExecServerLeases = new WeakMap<
+  CodexSandboxExecEnvironment,
+  CodexNodeExecServerLease
+>();
 
 /** Starts or reuses a sandbox exec-server and registers it with Codex app-server. */
 export async function ensureCodexSandboxExecServerEnvironment(params: {
   client: CodexAppServerClient;
   sandbox: SandboxContext | null;
+  runtime?: PluginRuntime;
   appServerStartOptions?: CodexAppServerStartOptions;
   timeoutMs?: number;
   signal?: AbortSignal;
+  onExecutionDisconnect?: (error: Error) => void;
 }): Promise<CodexSandboxExecEnvironment | undefined> {
-  if (!params.sandbox?.enabled || !params.sandbox.backend) {
+  if (!params.sandbox?.enabled) {
     return undefined;
   }
+  const placementNodeId = readCodexPlacementNodeId(params.sandbox);
+  if (!params.sandbox.backend && !placementNodeId) {
+    return undefined;
+  }
+  if (placementNodeId && !params.runtime) {
+    throw new Error("Codex paired-device execution requires its active plugin runtime.");
+  }
   if (!canExposeLocalExecServerToAppServer(params.appServerStartOptions)) {
     throw new Error(
       "OpenClaw Codex exec-server uses a local loopback URL and cannot be registered with a remote Codex app-server.",
     );
   }
-  const execServer = await acquireOpenClawExecServer(params.sandbox);
+  const { server: execServer, nodeLease } = await acquireOpenClawExecServer({
+    sandbox: params.sandbox,
+    runtime: params.runtime,
+    signal: params.signal,
+    onExecutionDisconnect: params.onExecutionDisconnect,
+  });
+  // Codex retains a thread's environment instance when its id and cwd stay equal.
+  // A single-use paired-node channel therefore needs a fresh selected identity.
+  const environmentId = nodeLease ? `openclaw-node-${nodeLease.id}` : execServer.environmentId;
   try {
+    const execServerUrl = nodeLease ? `${execServer.url}?lease=${nodeLease.id}` : execServer.url;
     await params.client.request(
       "environment/add",
       {
-        environmentId: execServer.environmentId,
-        execServerUrl: execServer.url,
+        environmentId,
+        execServerUrl,
       },
       { timeoutMs: params.timeoutMs, signal: params.signal },
     );
   } catch (error) {
+    if (nodeLease && "node" in execServer) {
+      closeCodexNodeExecServerLease(execServer, nodeLease);
+    }
     await releaseOpenClawExecServer(execServer);
     throw error;
   }
-  return {
-    environmentId: execServer.environmentId,
+  const environment = {
+    environmentId,
     cwd: params.sandbox.containerWorkdir,
   };
+  if (nodeLease) {
+    codexNodeExecServerLeases.set(environment, nodeLease);
+  }
+  return environment;
 }
 
 /** Releases the sandbox exec-server lease associated with a sandbox runtime. */
 export async function releaseCodexSandboxExecServerEnvironment(
   sandbox: SandboxContext | null | undefined,
+  environment?: CodexSandboxExecEnvironment,
 ): Promise<void> {
   if (!sandbox?.enabled) {
     return;
@@ -71,6 +113,11 @@ export async function releaseCodexSandboxExecServerEnvironment(
     .get(sandbox.runtimeId)
     ?.catch(() => undefined);
   if (server) {
+    const nodeLease = environment && codexNodeExecServerLeases.get(environment);
+    if (nodeLease && "node" in server) {
+      codexNodeExecServerLeases.delete(environment);
+      closeCodexNodeExecServerLease(server, nodeLease);
+    }
     await releaseOpenClawExecServer(server);
   }
 }
@@ -96,7 +143,13 @@ function canExposeLocalExecServerToAppServer(
   }
 }
 
-async function acquireOpenClawExecServer(sandbox: SandboxContext): Promise<OpenClawExecServer> {
+async function acquireOpenClawExecServer(params: {
+  sandbox: SandboxContext;
+  runtime?: PluginRuntime;
+  signal?: AbortSignal;
+  onExecutionDisconnect?: (error: Error) => void;
+}): Promise<{ server: OpenClawLeasedExecServer; nodeLease?: CodexNodeExecServerLease }> {
+  const { sandbox, runtime, signal, onExecutionDisconnect } = params;
   const key = sandbox.runtimeId;
   while (true) {
     const existing = sandboxExecServerRegistry.servers.get(key);
@@ -104,12 +157,67 @@ async function acquireOpenClawExecServer(sandbox: SandboxContext): Promise<OpenC
     const server = await promise;
     if (!server.closed && sandboxExecServerRegistry.servers.get(key) === promise) {
       server.refCount += 1;
-      return server;
+      if (!("node" in server)) {
+        return { server };
+      }
+      if (!runtime || !signal) {
+        await releaseOpenClawExecServer(server);
+        throw new Error("Codex paired-device execution requires an active runtime and attempt.");
+      }
+      try {
+        const placementIdentity = readCodexPlacementWorkspaceIdentity(sandbox);
+        // Capture the admitted caller's exact async scope before a detached WebSocket event.
+        const channel = await runtime.nodes.openDuplex({
+          nodeId: server.node.id,
+          command: "codex.exec-server.stdio.v1",
+          params: { cwd: sandbox.containerWorkdir, ...placementIdentity },
+          sessionKey: sandbox.sessionKey,
+          timeoutMs: 0,
+          maxMessageBytes: CODEX_NODE_EXEC_SERVER_MAX_MESSAGE_BYTES,
+          maxOutstandingDeliveryBytes: CODEX_NODE_EXEC_SERVER_MAX_MESSAGE_BYTES + 2 * 1024 * 1024,
+          signal,
+        });
+        if (
+          signal.aborted ||
+          server.closed ||
+          sandboxExecServerRegistry.servers.get(key) !== promise
+        ) {
+          channel.close();
+          throw new Error("Codex paired-device execution retired before its channel was ready.");
+        }
+        const nodeLease = {
+          id: randomUUID(),
+          channel,
+          claimed: false,
+          closed: false,
+          onDisconnected: onExecutionDisconnect,
+        };
+        server.node.leases.set(nodeLease.id, nodeLease);
+        // The approved child can exit before app-server claims its loopback socket.
+        // Observe that lifetime immediately instead of losing its terminal fact.
+        void channel.closed
+          .then(
+            () => handleClosedCodexNodeExecServerLease(server, nodeLease, { failed: false }),
+            (error: unknown) =>
+              handleClosedCodexNodeExecServerLease(server, nodeLease, { failed: true, error }),
+          )
+          .catch((error: unknown) => {
+            embeddedAgentLog.warn("codex paired-device exec-server lease cleanup failed", {
+              error: error instanceof Error ? error.message : String(error),
+            });
+          });
+        return { server, nodeLease };
+      } catch (error) {
+        await releaseOpenClawExecServer(server);
+        throw error;
+      }
     }
   }
 }
 
-function startAndRememberOpenClawExecServer(sandbox: SandboxContext): Promise<OpenClawExecServer> {
+function startAndRememberOpenClawExecServer(
+  sandbox: SandboxContext,
+): Promise<OpenClawLeasedExecServer> {
   const created = startOpenClawExecServer(sandbox);
   const key = sandbox.runtimeId;
   sandboxExecServerRegistry.servers.set(key, created);
@@ -121,21 +229,37 @@ function startAndRememberOpenClawExecServer(sandbox: SandboxContext): Promise<Op
   return created;
 }
 
-async function startOpenClawExecServer(sandbox: SandboxContext): Promise<OpenClawExecServer> {
+async function startOpenClawExecServer(sandbox: SandboxContext): Promise<OpenClawLeasedExecServer> {
   const backend = sandbox.backend;
   const fsBridge = sandbox.fsBridge;
-  if (!backend) {
-    throw new Error("OpenClaw sandbox backend is unavailable.");
-  }
-  if (!fsBridge) {
-    throw new Error("Sandbox filesystem bridge is unavailable.");
+  const placementNodeId = readCodexPlacementNodeId(sandbox);
+  let connection:
+    | { kind: "node"; id: string }
+    | {
+        kind: "sandbox";
+        backend: NonNullable<SandboxContext["backend"]>;
+        fsBridge: NonNullable<SandboxContext["fsBridge"]>;
+      };
+  if (placementNodeId) {
+    connection = { kind: "node", id: placementNodeId };
+  } else {
+    if (!backend) {
+      throw new Error("OpenClaw sandbox backend is unavailable.");
+    }
+    if (!fsBridge) {
+      throw new Error("Sandbox filesystem bridge is unavailable.");
+    }
+    connection = { kind: "sandbox", backend, fsBridge };
   }
   const server = new WebSocketServer({
     host: "127.0.0.1",
     port: 0,
     // Match ws' historical default: Codex fs/writeFile sends one base64 JSON-RPC
     // frame, while the socket error handler below makes oversize frames nonfatal.
-    maxPayload: CODEX_SANDBOX_EXEC_SERVER_MAX_INBOUND_MESSAGE_BYTES,
+    maxPayload:
+      connection.kind === "node"
+        ? CODEX_NODE_EXEC_SERVER_MAX_MESSAGE_BYTES
+        : CODEX_SANDBOX_EXEC_SERVER_MAX_INBOUND_MESSAGE_BYTES,
   });
   await once(server, "listening");
   const address = server.address();
@@ -145,19 +269,21 @@ async function startOpenClawExecServer(sandbox: SandboxContext): Promise<OpenCla
   const environmentId = buildEnvironmentId(sandbox);
   const authPath = `/openclaw-${randomUUID()}`;
   const url = `ws://127.0.0.1:${(address as AddressInfo).port}${authPath}`;
-  const execServer: OpenClawExecServer = {
+  const common = {
     authPath,
     closed: false,
     environmentId,
     refCount: 0,
     url,
     sandbox,
-    backend,
-    fsBridge,
     server,
-    children: new Set(),
-    cleanupTasks: new Set(),
+    children: new Set<SandboxChildOwner>(),
+    cleanupTasks: new Set<Promise<void>>(),
   };
+  const execServer: OpenClawLeasedExecServer =
+    connection.kind === "node"
+      ? { ...common, node: { id: connection.id, leases: new Map() } }
+      : { ...common, backend: connection.backend, fsBridge: connection.fsBridge };
   server.on("connection", (socket, request) => {
     // ws emits error for maxPayload rejections before auth or JSON-RPC sees the frame.
     socket.on("error", handleExecServerSocketError);
@@ -165,6 +291,10 @@ async function startOpenClawExecServer(sandbox: SandboxContext): Promise<OpenCla
       socket.close(1008, "unauthorized");
       return;
     }
+    if ("node" in execServer) {
+      handleNodeConnection(execServer, socket, request);
+      return;
+    }
     handleConnection(execServer, socket);
   });
   embeddedAgentLog.info("codex sandbox exec-server started", {
@@ -175,7 +305,7 @@ async function startOpenClawExecServer(sandbox: SandboxContext): Promise<OpenCla
   return execServer;
 }
 
-async function releaseOpenClawExecServer(execServer: OpenClawExecServer): Promise<void> {
+async function releaseOpenClawExecServer(execServer: OpenClawLeasedExecServer): Promise<void> {
   if (execServer.closed) {
     return;
   }
@@ -201,13 +331,122 @@ function buildEnvironmentId(sandbox: SandboxContext): string {
 }
 
 function isAuthorizedExecServerRequest(
-  execServer: OpenClawExecServer,
+  execServer: OpenClawLeasedExecServer,
   request: IncomingMessage,
 ): boolean {
   const url = new URL(request.url ?? "", "ws://127.0.0.1");
   return url.pathname === execServer.authPath;
 }
 
+function readCodexPlacementNodeId(sandbox: SandboxContext): string | undefined {
+  if (
+    !("placementExecutionMode" in sandbox) ||
+    sandbox.placementExecutionMode !== "remote-exec" ||
+    !("placementNodeId" in sandbox) ||
+    typeof sandbox.placementNodeId !== "string" ||
+    !sandbox.placementNodeId
+  ) {
+    return undefined;
+  }
+  return sandbox.placementNodeId;
+}
+
+function readCodexPlacementWorkspaceIdentity(sandbox: SandboxContext): {
+  environmentId: string;
+  sessionId: string;
+  ownerEpoch: number;
+  sessionKey: string;
+} {
+  if (
+    !("placementEnvironmentId" in sandbox) ||
+    typeof sandbox.placementEnvironmentId !== "string" ||
+    !sandbox.placementEnvironmentId ||
+    sandbox.placementEnvironmentId.trim() !== sandbox.placementEnvironmentId ||
+    !("placementSessionId" in sandbox) ||
+    typeof sandbox.placementSessionId !== "string" ||
+    !sandbox.placementSessionId ||
+    sandbox.placementSessionId.trim() !== sandbox.placementSessionId ||
+    !("placementOwnerEpoch" in sandbox) ||
+    typeof sandbox.placementOwnerEpoch !== "number" ||
+    !Number.isSafeInteger(sandbox.placementOwnerEpoch) ||
+    sandbox.placementOwnerEpoch < 1 ||
+    !sandbox.sessionKey ||
+    sandbox.sessionKey.trim() !== sandbox.sessionKey
+  ) {
+    throw new Error(
+      "Codex paired-device execution requires its exact placement workspace identity.",
+    );
+  }
+  return {
+    environmentId: sandbox.placementEnvironmentId,
+    sessionId: sandbox.placementSessionId,
+    ownerEpoch: sandbox.placementOwnerEpoch,
+    sessionKey: sandbox.sessionKey,
+  };
+}
+
+function handleNodeConnection(
+  execServer: OpenClawNodeExecServer,
+  socket: WebSocket,
+  request: IncomingMessage,
+): void {
+  const leaseId = new URL(request.url ?? "", "ws://127.0.0.1").searchParams.get("lease");
+  const lease = leaseId ? execServer.node.leases.get(leaseId) : undefined;
+  if (!lease || lease.claimed || lease.closed) {
+    socket.close(1008, "execution channel unavailable");
+    return;
+  }
+  // stdio has exactly one connection; a fresh attempt always owns a fresh channel.
+  lease.claimed = true;
+  const cleanup = startCodexNodeExecServerRelay({ lease, socket });
+  execServer.cleanupTasks.add(cleanup);
+  void cleanup.then(
+    () => execServer.cleanupTasks.delete(cleanup),
+    (error: unknown) => {
+      execServer.cleanupTasks.delete(cleanup);
+      embeddedAgentLog.warn("codex paired-device exec-server relay failed", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    },
+  );
+}
+
+function closeCodexNodeExecServerLease(
+  execServer: OpenClawNodeExecServer,
+  lease: CodexNodeExecServerLease,
+): void {
+  execServer.node.leases.delete(lease.id);
+  if (!lease.closed) {
+    lease.closed = true;
+    lease.closeRelay?.();
+    lease.channel.close();
+  }
+}
+
+function handleClosedCodexNodeExecServerLease(
+  execServer: OpenClawNodeExecServer,
+  lease: CodexNodeExecServerLease,
+  result: { failed: boolean; error?: unknown },
+): void {
+  if (lease.closed) {
+    return;
+  }
+  if (lease.onChannelClosed) {
+    lease.onChannelClosed(result);
+    return;
+  }
+  try {
+    lease.onDisconnected?.(
+      createCodexNodeExecServerDisconnectError(
+        result.failed ? "execution device failed" : "execution device disconnected",
+        result.error,
+      ),
+    );
+  } finally {
+    closeCodexNodeExecServerLease(execServer, lease);
+  }
+}
+
 function handleConnection(execServer: OpenClawExecServer, socket: WebSocket): void {
   const session = new CodexSandboxExecSession(execServer, {
     isOpen: () => socket.readyState === socket.OPEN,
diff --git a/extensions/codex/src/app-server/sandbox-exec-server/types.ts b/extensions/codex/src/app-server/sandbox-exec-server/types.ts
index ac302e730959..39a27cce16e2 100644
--- a/extensions/codex/src/app-server/sandbox-exec-server/types.ts
+++ b/extensions/codex/src/app-server/sandbox-exec-server/types.ts
@@ -2,6 +2,7 @@
  * Shared protocol and runtime state types for the Codex sandbox exec-server
  * transport-neutral execution session.
  */
+import type { PluginRuntime } from "openclaw/plugin-sdk/plugin-runtime";
 import type { SandboxContext } from "openclaw/plugin-sdk/sandbox";
 import type { JsonObject, JsonValue } from "../protocol.js";
 import type { SandboxChildOwner } from "./sandbox-child.js";
@@ -91,16 +92,14 @@ export type ManagedProcess = {
   evictProcess: () => void;
 };
 
-/** Shared exec-server instance leased by Codex native sandbox environments. */
-export type OpenClawExecServer = {
+/** Common loopback server and lease ownership shared by both execution transports. */
+type OpenClawExecServerLease = {
   environmentId: string;
   authPath: string;
   refCount: number;
   closed: boolean;
   url: string;
   sandbox: SandboxContext;
-  backend: NonNullable<SandboxContext["backend"]>;
-  fsBridge: NonNullable<SandboxContext["fsBridge"]>;
   server: {
     clients: Iterable<{ close: (code?: number, reason?: string) => void }>;
     close: (callback: (error?: Error) => void) => void;
@@ -108,3 +107,31 @@ export type OpenClawExecServer = {
   children: Set<SandboxChildOwner>;
   cleanupTasks: Set<Promise<void>>;
 };
+
+/** Locally interpreted exec-server protocol backed by an OpenClaw sandbox. */
+export type OpenClawExecServer = OpenClawExecServerLease & {
+  backend: NonNullable<SandboxContext["backend"]>;
+  fsBridge: NonNullable<SandboxContext["fsBridge"]>;
+};
+
+/** One pre-authorized, single-use Codex stdio connection. */
+export type CodexNodeExecServerLease = {
+  id: string;
+  channel: Awaited<ReturnType<PluginRuntime["nodes"]["openDuplex"]>>;
+  claimed: boolean;
+  closed: boolean;
+  closeRelay?: () => void;
+  onDisconnected?: (error: Error) => void;
+  onChannelClosed?: (result: { failed: boolean; error?: unknown }) => void;
+};
+
+/** Opaque exec-server relay backed by the exact prepared paired-device placement. */
+export type OpenClawNodeExecServer = OpenClawExecServerLease & {
+  node: {
+    id: string;
+    leases: Map<string, CodexNodeExecServerLease>;
+  };
+};
+
+/** One canonical loopback/refcount owner with either local or node connection handling. */
+export type OpenClawLeasedExecServer = OpenClawExecServer | OpenClawNodeExecServer;
diff --git a/extensions/codex/src/app-server/side-question.test.ts b/extensions/codex/src/app-server/side-question.test.ts
index a7a7c3bbcf21..f2da4c8146ee 100644
--- a/extensions/codex/src/app-server/side-question.test.ts
+++ b/extensions/codex/src/app-server/side-question.test.ts
@@ -690,7 +690,7 @@ describe("runCodexAppServerSideQuestion", () => {
     expect(injectParams?.items).toHaveLength(1);
     expect(injectParams?.items?.[0]?.type).toBe("message");
     expect(injectParams?.items?.[0]?.role).toBe("user");
-    expect(injectCall?.[2]).toEqual({ timeoutMs: 60_000, signal: undefined });
+    expect(injectCall?.[2]).toEqual({ timeoutMs: 60_000, signal: expect.any(AbortSignal) });
     const injectedItem = injectParams?.items?.[0] as
       | { content?: Array<{ text?: string }> }
       | undefined;
@@ -720,7 +720,7 @@ describe("runCodexAppServerSideQuestion", () => {
           },
         },
       },
-      { timeoutMs: 60_000, signal: undefined },
+      { timeoutMs: 60_000, signal: expect.any(AbortSignal) },
     ]);
     const turnStartParams = turnStartCall?.[1] as Record<string, unknown> | undefined;
     expect(turnStartParams).not.toHaveProperty("approvalPolicy");
@@ -856,6 +856,42 @@ describe("runCodexAppServerSideQuestion", () => {
     });
   });
 
+  it("rejects paired-device side questions before acquiring a client, channel, or approval", async () => {
+    const client = createFakeClient();
+    getSharedCodexAppServerClientMock.mockResolvedValue(client);
+    const openDuplex = vi.fn(async () => {
+      throw new Error("paired-device side-question channel was opened");
+    });
+    const requestApproval = vi.fn(async () => undefined);
+    const sandbox = {
+      ...createSandboxContext({}),
+      placementExecutionMode: "remote-exec" as const,
+      placementNodeId: "paired-device-1",
+      placementEnvironmentId: "environment-1",
+      placementSessionId: "session-1",
+      placementOwnerEpoch: 1,
+      sessionKey: "agent:main:session-1",
+    };
+
+    await expect(
+      runCodexAppServerSideQuestion(
+        sideParams({
+          sandbox,
+          hostCapabilities: { ...TEST_HOST_CAPABILITIES, requestApproval },
+        }),
+        { runtime: { nodes: { openDuplex } } as never },
+      ),
+    ).rejects.toThrow(
+      "Normal Codex turns are supported on paired devices, but /btw is not yet bound to the active placement.",
+    );
+
+    expect(getSharedCodexAppServerClientMock).not.toHaveBeenCalled();
+    expect(openDuplex).not.toHaveBeenCalled();
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(client.request).not.toHaveBeenCalled();
+    expect(createOpenClawCodingToolsMock).not.toHaveBeenCalled();
+  });
+
   it("rebinds side-question handlers when selection retry replaces the client", async () => {
     const initialClient = createFakeClient();
     const replacementClient = createFakeClient();
diff --git a/extensions/codex/src/app-server/side-question.ts b/extensions/codex/src/app-server/side-question.ts
index 1f513ce5a14c..de34ca5c0e1c 100644
--- a/extensions/codex/src/app-server/side-question.ts
+++ b/extensions/codex/src/app-server/side-question.ts
@@ -18,6 +18,7 @@ import {
   type NativeHookRelayRegistrationHandle,
 } from "openclaw/plugin-sdk/agent-harness-runtime";
 import { loadExecApprovals } from "openclaw/plugin-sdk/exec-approvals-runtime";
+import type { PluginRuntime } from "openclaw/plugin-sdk/plugin-runtime";
 import { readStringField as readString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { resolveCodexAppServerForModelProvider } from "./app-server-policy.js";
 import { handleCodexAppServerApprovalRequest } from "./approval-bridge.js";
@@ -39,6 +40,7 @@ import {
 } from "./client.js";
 import {
   canUseCodexModelBackedApprovalsReviewerForModel,
+  isCodexPairedNodeRemoteExecPlacementSandbox,
   isCodexRemoteExecPlacementSandbox,
   isCodexSandboxExecServerEnabled,
   readCodexPluginConfig,
@@ -51,6 +53,7 @@ import {
 import {
   resolveCodexExternalSandboxPolicyForOpenClawSandbox,
   resolveCodexMessageToolProvider,
+  resolveCodexNodePlacementToolConstructionPlan,
   resolveCodexSandboxEnvironmentSelection,
   shouldEnableCodexAppServerNativeToolSurface,
   shouldRequireCodexSandboxExecServerEnvironment,
@@ -171,6 +174,7 @@ export async function runCodexAppServerSideQuestion(
   params: AgentHarnessSideQuestionParamsV2,
   options: {
     bindingStore: CodexAppServerBindingStore;
+    runtime?: PluginRuntime;
     pluginConfig?: unknown;
     /** Private app-server request identity; public side-run identity remains params.model. */
     runtimeModelId?: string;
@@ -196,6 +200,11 @@ export async function runCodexAppServerSideQuestion(
       "Codex /btw needs an active Codex thread. Send a normal message first, then try /btw again.",
     );
   }
+  if (isCodexPairedNodeRemoteExecPlacementSandbox(params.sandbox)) {
+    throw new Error(
+      "Normal Codex turns are supported on paired devices, but /btw is not yet bound to the active placement.",
+    );
+  }
   const pluginConfig = readCodexPluginConfig(options.pluginConfig);
   const { sessionAgentId } = resolveSessionAgentIds({
     sessionKey: params.sessionKey,
@@ -413,9 +422,10 @@ export async function runCodexAppServerSideQuestion(
     if (!sandboxEnvironment) {
       return;
     }
+    const environment = sandboxEnvironment;
     sandboxEnvironment = undefined;
     sandboxEnvironmentClient = undefined;
-    await releaseCodexSandboxExecServerEnvironment(params.sandbox);
+    await releaseCodexSandboxExecServerEnvironment(params.sandbox, environment);
   };
   const ensureSandboxEnvironment = async (targetClient: CodexAppServerClient) => {
     if (!sandboxEnvironmentRequired || sandboxEnvironmentClient === targetClient) {
@@ -425,9 +435,15 @@ export async function runCodexAppServerSideQuestion(
     const environment = await ensureCodexSandboxExecServerEnvironment({
       client: targetClient,
       sandbox: params.sandbox ?? null,
+      runtime: options.runtime,
       appServerStartOptions: appServer.start,
       timeoutMs: appServer.requestTimeoutMs,
       signal: runAbortController.signal,
+      onExecutionDisconnect: (error) => {
+        collector.reject(error);
+        embeddedAgentLog.warn(error.message);
+        runAbortController.abort("client_closed");
+      },
     });
     if (!environment) {
       throw new Error(
@@ -680,7 +696,7 @@ export async function runCodexAppServerSideQuestion(
       await withLeasedCodexAppServerClientStartSelectionRetry({
         lease: clientLease,
         options: clientOptions,
-        signal: params.opts?.abortSignal,
+        signal: runAbortController.signal,
         run: async (forkClient, requestOptions) => {
           await ensureSandboxEnvironment(forkClient);
           const executionCwd = sandboxEnvironment?.cwd ?? cwd;
@@ -725,7 +741,7 @@ export async function runCodexAppServerSideQuestion(
         threadId: childThreadId,
         items: [sideBoundaryPromptItem()],
       },
-      { timeoutMs: appServer.requestTimeoutMs, signal: params.opts?.abortSignal },
+      { timeoutMs: appServer.requestTimeoutMs, signal: runAbortController.signal },
     );
 
     const effort = usesSupervisionConnection
@@ -771,7 +787,7 @@ export async function runCodexAppServerSideQuestion(
                   },
                 }),
           },
-          { timeoutMs: appServer.requestTimeoutMs, signal: params.opts?.abortSignal },
+          { timeoutMs: appServer.requestTimeoutMs, signal: runAbortController.signal },
         )
         .catch((error: unknown) => {
           if (isCodexAppServerIndeterminateRequestCancellationError(error)) {
@@ -803,7 +819,7 @@ export async function runCodexAppServerSideQuestion(
     let text: string;
     try {
       text = await collector.wait({
-        signal: params.opts?.abortSignal,
+        signal: runAbortController.signal,
         timeoutMs: Math.max(
           appServer.turnCompletionIdleTimeoutMs,
           SIDE_QUESTION_COMPLETION_TIMEOUT_MS,
@@ -1042,6 +1058,10 @@ async function createCodexSideToolBridge(input: {
             sessionKey: sandboxSessionKey,
             workspaceDir: input.cwd,
           });
+    const toolConstructionPlan = resolveCodexNodePlacementToolConstructionPlan(
+      sandbox,
+      input.nativeToolSurfaceEnabled,
+    );
     const allTools = createOpenClawCodingTools({
       agentId: input.sessionAgentId,
       sessionKey: sandboxSessionKey,
@@ -1114,6 +1134,7 @@ async function createCodexSideToolBridge(input: {
         currentChannelId: input.params.currentChannelId,
       }).channelId,
       sandbox,
+      ...(toolConstructionPlan ? { toolConstructionPlan } : {}),
       emitBeforeToolCallDiagnostics: false,
       modelHasVision: runtimeModel.input?.includes("image") ?? false,
       requireExplicitMessageTarget: true,
@@ -1413,7 +1434,7 @@ class CodexSideQuestionCollector {
     settle?.resolve(text);
   }
 
-  private reject(error: string | Error): void {
+  reject(error: string | Error): void {
     this.terminalError = error instanceof Error ? error : new Error(error);
     const settle = this.settle;
     this.settle = undefined;
diff --git a/extensions/codex/src/app-server/transport-stdio.ts b/extensions/codex/src/app-server/transport-stdio.ts
index 0340f2635521..3ed66c4bcf5c 100644
--- a/extensions/codex/src/app-server/transport-stdio.ts
+++ b/extensions/codex/src/app-server/transport-stdio.ts
@@ -2,13 +2,12 @@
  * Creates and configures stdio-backed Codex app-server transports, including
  * Windows spawn normalization and environment filtering.
  */
-import { spawn } from "node:child_process";
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import {
   materializeWindowsSpawnProgram,
   resolveWindowsSpawnProgram,
 } from "openclaw/plugin-sdk/windows-spawn";
 import type { CodexAppServerStartOptions } from "./config.js";
-import type { CodexAppServerTransport } from "./transport.js";
 
 const UNSAFE_ENVIRONMENT_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 const RUNTIME_INJECTION_ENVIRONMENT_KEYS = new Set([
@@ -124,8 +123,11 @@ function copySafeEnvironmentEntries(
 }
 
 /** Spawns the Codex app-server process and returns the shared transport interface. */
-export function createStdioTransport(options: CodexAppServerStartOptions): CodexAppServerTransport {
-  const env = resolveCodexAppServerSpawnEnv(options);
+export function createStdioTransport(
+  options: CodexAppServerStartOptions,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): ChildProcessWithoutNullStreams {
+  const env = resolveCodexAppServerSpawnEnv(options, baseEnv);
   const invocation = resolveCodexAppServerSpawnInvocation(options, {
     platform: process.platform,
     env,
diff --git a/extensions/codex/src/node-exec-server.runtime.ts b/extensions/codex/src/node-exec-server.runtime.ts
new file mode 100644
index 000000000000..6d7cc416b643
--- /dev/null
+++ b/extensions/codex/src/node-exec-server.runtime.ts
@@ -0,0 +1,287 @@
+/** Owns approved, connection-bound Codex exec-server processes on paired nodes. */
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { once } from "node:events";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import type { OpenClawPluginNodeHostCommandIo } from "openclaw/plugin-sdk/node-host";
+import { killProcessTree } from "openclaw/plugin-sdk/process-runtime";
+import { sanitizeEnvVars } from "openclaw/plugin-sdk/sandbox";
+import { isRecord } from "openclaw/plugin-sdk/string-coerce-runtime";
+import { resolvePreferredOpenClawTmpDir, withTempWorkspace } from "openclaw/plugin-sdk/temp-path";
+import {
+  isManagedCodexDesktopCommand,
+  resolveManagedCodexAppServerStartOptions,
+  resolveManagedCodexNativeCommand,
+} from "./app-server/managed-binary.js";
+import { createStdioTransport } from "./app-server/transport-stdio.js";
+import { closeCodexAppServerTransportAndWait } from "./app-server/transport.js";
+
+const MAX_CODEX_EXEC_SERVER_MESSAGE_BYTES = 64 * 1024 * 1024;
+const MAX_CODEX_EXEC_SERVER_STDERR_BYTES = 4 * 1024;
+const CODEX_EXEC_SERVER_TERMINATION_GRACE_MS = 1_000;
+const CODEX_EXEC_SERVER_REAP_TIMEOUT_MS = 5_000;
+const NODE_EXEC_SERVER_PLATFORM_ENVIRONMENT =
+  /^(?:SYSTEMROOT|WINDIR|COMSPEC|PATHEXT|TEMP|TMP|TMPDIR)$/iu;
+
+type CodexNodeExecProcessOwner = {
+  terminate: () => Promise<void>;
+};
+
+function validateNodeExecServerMessage(message: Uint8Array): Buffer {
+  if (message.byteLength === 0 || message.byteLength > MAX_CODEX_EXEC_SERVER_MESSAGE_BYTES) {
+    throw new Error("Codex exec-server JSON-RPC message exceeds its 64 MiB limit.");
+  }
+  const encoded = Buffer.from(message.buffer, message.byteOffset, message.byteLength);
+  if (encoded.includes(0x0a) || encoded.includes(0x0d)) {
+    throw new Error("Codex exec-server JSON-RPC frames must contain exactly one message.");
+  }
+  let decoded: unknown;
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(encoded);
+    decoded = JSON.parse(text) as unknown;
+  } catch {
+    throw new Error("Codex exec-server received malformed UTF-8 or JSON-RPC.");
+  }
+  if (
+    !isRecord(decoded) ||
+    (decoded.jsonrpc !== undefined && decoded.jsonrpc !== "2.0") ||
+    (typeof decoded.method !== "string" &&
+      !("id" in decoded && ("result" in decoded || "error" in decoded)))
+  ) {
+    throw new Error("Codex exec-server received an invalid JSON-RPC message.");
+  }
+  return encoded;
+}
+
+function nodeExecServerAbortError(signal: AbortSignal): Error {
+  return signal.reason instanceof Error
+    ? signal.reason
+    : new Error("Codex node exec-server connection closed.");
+}
+
+function writeNodeExecServerMessage(
+  child: ChildProcessWithoutNullStreams,
+  message: Buffer,
+  signal: AbortSignal,
+): Promise<void> | void {
+  if (signal.aborted) {
+    throw nodeExecServerAbortError(signal);
+  }
+  const payload = Buffer.concat([message, Buffer.from("\n")]);
+  if (!child.stdin.write(payload)) {
+    return once(child.stdin, "drain", { signal }).then(() => undefined);
+  }
+}
+
+async function relayNodeExecServerOutput(
+  child: ChildProcessWithoutNullStreams,
+  send: (message: Uint8Array) => Promise<void>,
+): Promise<void> {
+  let fragments: Buffer[] = [];
+  let pendingBytes = 0;
+  for await (const rawChunk of child.stdout) {
+    const chunk = Buffer.isBuffer(rawChunk) ? rawChunk : Buffer.from(rawChunk);
+    let offset = 0;
+    while (offset < chunk.byteLength) {
+      const newline = chunk.indexOf(0x0a, offset);
+      const fragment = chunk.subarray(offset, newline === -1 ? chunk.byteLength : newline);
+      const nextLength = pendingBytes + fragment.byteLength;
+      if (nextLength > MAX_CODEX_EXEC_SERVER_MESSAGE_BYTES + 1) {
+        throw new Error("Codex exec-server stdout message exceeds its 64 MiB limit.");
+      }
+      if (fragment.byteLength > 0) {
+        fragments.push(fragment);
+      }
+      pendingBytes = nextLength;
+      if (newline === -1) {
+        if (
+          pendingBytes > MAX_CODEX_EXEC_SERVER_MESSAGE_BYTES &&
+          fragment[fragment.byteLength - 1] !== 0x0d
+        ) {
+          throw new Error("Codex exec-server stdout message exceeds its 64 MiB limit.");
+        }
+        break;
+      }
+      const trailing = fragments.at(-1);
+      if (trailing?.[trailing.byteLength - 1] === 0x0d) {
+        pendingBytes -= 1;
+        if (trailing.byteLength === 1) {
+          fragments.pop();
+        } else {
+          fragments[fragments.length - 1] = trailing.subarray(0, trailing.byteLength - 1);
+        }
+      }
+      const pending =
+        fragments.length === 1 ? fragments[0]! : Buffer.concat(fragments, pendingBytes);
+      const message = validateNodeExecServerMessage(pending);
+      fragments = [];
+      pendingBytes = 0;
+      await send(message);
+      offset = newline + 1;
+    }
+  }
+  if (pendingBytes > 0) {
+    throw new Error("Codex exec-server stdout ended with an unterminated JSON-RPC message.");
+  }
+}
+
+function createNodeExecServerProcessOwner(
+  child: ChildProcessWithoutNullStreams,
+  closed: Promise<{ code: number | null; signal: NodeJS.Signals | null }>,
+): CodexNodeExecProcessOwner {
+  let termination: Promise<void> | undefined;
+  return {
+    terminate: () =>
+      (termination ??= (async () => {
+        // The shared transport closes only the root on Windows; taskkill /T
+        // owns its descendants before that root can disappear.
+        if (process.platform === "win32" && child.pid) {
+          killProcessTree(child.pid, { graceMs: CODEX_EXEC_SERVER_TERMINATION_GRACE_MS });
+        }
+        const exited = await closeCodexAppServerTransportAndWait(child, {
+          forceKillDelayMs: CODEX_EXEC_SERVER_TERMINATION_GRACE_MS,
+          exitTimeoutMs: CODEX_EXEC_SERVER_REAP_TIMEOUT_MS,
+        });
+        if (!exited) {
+          throw new Error("Codex node exec-server process tree did not terminate.");
+        }
+        await closed;
+      })()),
+  };
+}
+
+/** Runs the one-connection paired-node exec-server after lightweight command admission. */
+export async function runCodexNodeExecServer(params: {
+  workspaceDir: string;
+  io: OpenClawPluginNodeHostCommandIo;
+  activeProcesses: Set<() => Promise<void>>;
+  onFrameReceiver: (receiver: (message: Uint8Array) => Promise<void> | void) => void;
+}): Promise<string> {
+  const { io } = params;
+  const frames = io.frames;
+  if (!frames) {
+    throw new Error("Codex node exec-server requires duplex frames.");
+  }
+  const cwd = params.workspaceDir;
+  let writes: Promise<void> | undefined;
+  let rejectDisconnected!: (error: Error) => void;
+  const disconnected = new Promise<never>((_resolve, reject) => {
+    rejectDisconnected = reject;
+  });
+  void disconnected.catch(() => {});
+  const onAbort = () => {
+    const error = nodeExecServerAbortError(io.signal);
+    rejectDisconnected(error);
+  };
+  io.signal.addEventListener("abort", onAbort, { once: true });
+
+  try {
+    if (io.signal.aborted) {
+      throw nodeExecServerAbortError(io.signal);
+    }
+    return await withTempWorkspace(
+      { rootDir: resolvePreferredOpenClawTmpDir(), prefix: "codex-node-exec-server-" },
+      async ({ dir }) => {
+        const codexHome = path.join(dir, ".codex");
+        // Codex canonicalizes CODEX_HOME during startup and rejects missing directories.
+        await mkdir(codexHome, { recursive: true, mode: 0o700 });
+        const resolved = await resolveManagedCodexAppServerStartOptions({
+          transport: "stdio",
+          command: "codex",
+          commandSource: "managed",
+          managedCommandOrder: "package-first",
+          args: ["exec-server", "--listen", "stdio"],
+          headers: {},
+        });
+        const native = resolveManagedCodexNativeCommand(resolved.command);
+        if (!native || isManagedCodexDesktopCommand(resolved.command)) {
+          throw new Error("Codex node exec-server requires the pinned managed package binary.");
+        }
+        // The exec-server needs platform/locale basics, never provider, forge,
+        // cloud, SSH-agent, XDG, or runtime-injection state from its node host.
+        const baseEnv = sanitizeEnvVars(process.env, {
+          strictMode: true,
+          customAllowedPatterns: [NODE_EXEC_SERVER_PLATFORM_ENVIRONMENT],
+        }).allowed;
+        if (io.signal.aborted) {
+          throw nodeExecServerAbortError(io.signal);
+        }
+        const child = createStdioTransport(
+          {
+            transport: "stdio",
+            command: native,
+            commandSource: "resolved-managed",
+            args: resolved.args,
+            headers: {},
+            cwd,
+            env: {
+              HOME: dir,
+              CODEX_HOME: codexHome,
+              ...(process.platform === "win32" ? { USERPROFILE: dir } : {}),
+            },
+            clearEnv: ["NODE_OPTIONS"],
+          },
+          baseEnv,
+        );
+        child.stdin.on("error", (error) => {
+          rejectDisconnected(error);
+        });
+        let stderr = Buffer.alloc(0);
+        child.stderr.on("data", (chunk: Buffer | string) => {
+          const next = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+          const bounded = next.subarray(-MAX_CODEX_EXEC_SERVER_STDERR_BYTES);
+          stderr = Buffer.concat([stderr, bounded]).subarray(-MAX_CODEX_EXEC_SERVER_STDERR_BYTES);
+        });
+        const closed = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>(
+          (resolve) => {
+            child.once("close", (code, signal) => resolve({ code, signal }));
+          },
+        );
+        child.once("error", (error) => {
+          rejectDisconnected(error);
+        });
+        const owner = createNodeExecServerProcessOwner(child, closed);
+        params.activeProcesses.add(owner.terminate);
+        const output = relayNodeExecServerOutput(child, frames.send.bind(frames));
+        void output.catch((error: unknown) => {
+          rejectDisconnected(error instanceof Error ? error : new Error(String(error)));
+        });
+        try {
+          if (io.signal.aborted) {
+            throw nodeExecServerAbortError(io.signal);
+          }
+          // Registration publishes framed readiness; avoid promising it before
+          // the child and every cleanup/error owner can consume incoming frames.
+          params.onFrameReceiver((message) => {
+            const encoded = validateNodeExecServerMessage(message);
+            const operation = writes
+              ? writes.then(() => writeNodeExecServerMessage(child, encoded, io.signal))
+              : writeNodeExecServerMessage(child, encoded, io.signal);
+            if (!operation) {
+              return undefined;
+            }
+            const observed = operation.catch(() => {});
+            writes = observed;
+            void observed.then(() => {
+              if (writes === observed) {
+                writes = undefined;
+              }
+            });
+            return operation;
+          });
+          const outcome = await Promise.race([closed, disconnected]);
+          const diagnostic = stderr.toString("utf8").trim();
+          throw new Error(
+            `Codex node exec-server exited (code ${outcome.code ?? "none"}, signal ${outcome.signal ?? "none"})${diagnostic ? `: ${diagnostic}` : "."}`,
+          );
+        } finally {
+          await owner.terminate();
+          params.activeProcesses.delete(owner.terminate);
+          await Promise.allSettled([output, ...(writes ? [writes] : [])]);
+        }
+      },
+    );
+  } finally {
+    io.signal.removeEventListener("abort", onAbort);
+  }
+}
diff --git a/extensions/codex/src/node-exec-server.test.ts b/extensions/codex/src/node-exec-server.test.ts
new file mode 100644
index 000000000000..6181227c3034
--- /dev/null
+++ b/extensions/codex/src/node-exec-server.test.ts
@@ -0,0 +1,673 @@
+/** Protects paired-node policy, real pinned Codex stdio framing, and child cleanup. */
+import { once } from "node:events";
+import { access, readFile, realpath } from "node:fs/promises";
+import { createServer } from "node:http";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { OpenClawPluginNodeHostCommandIo } from "openclaw/plugin-sdk/node-host";
+import type {
+  OpenClawPluginNodeHostCommand,
+  OpenClawPluginNodeInvokePolicyContext,
+} from "openclaw/plugin-sdk/plugin-entry";
+import { resolvePreferredOpenClawTmpDir, withTempWorkspace } from "openclaw/plugin-sdk/temp-path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createCodexNodeExecServerCommand,
+  createCodexNodeExecServerInvokePolicy,
+} from "./node-exec-server.js";
+
+type JsonRpcRecord = Record<string, unknown>;
+const CODEX_NODE_EXEC_SERVER_COMMAND = "codex.exec-server.stdio.v1";
+
+function createManagedWorkspaceInvocation(cwd: string) {
+  const placement = {
+    cwd,
+    environmentId: "paired-environment",
+    sessionId: "paired-session",
+    ownerEpoch: 1,
+    sessionKey: "agent:main:paired-session",
+  };
+  const release = vi.fn();
+  const acquireManagedWorkspace = vi.fn(
+    (request: {
+      workspaceDir: string;
+      environmentId: string;
+      sessionId: string;
+      ownerEpoch: number;
+      sessionKey: string;
+    }) => {
+      if (
+        request.workspaceDir !== cwd ||
+        request.environmentId !== placement.environmentId ||
+        request.sessionId !== placement.sessionId ||
+        request.ownerEpoch !== placement.ownerEpoch ||
+        request.sessionKey !== placement.sessionKey
+      ) {
+        throw new Error("node placement does not own the requested workspace");
+      }
+      return { workspaceDir: cwd, release };
+    },
+  );
+  const context = {
+    sessionKey: placement.sessionKey,
+    sendNodeEvent: async () => undefined,
+    acquireManagedWorkspace,
+  } satisfies NonNullable<Parameters<OpenClawPluginNodeHostCommand["handle"]>[2]>;
+  return { placement, context, acquireManagedWorkspace, release };
+}
+
+function createNodeFrames() {
+  const controller = new AbortController();
+  let receive: ((message: Uint8Array) => void | Promise<void>) | undefined;
+  let signalReady = () => {};
+  const ready = new Promise<void>((resolve) => {
+    signalReady = resolve;
+  });
+  const outbound: JsonRpcRecord[] = [];
+  const io: OpenClawPluginNodeHostCommandIo = {
+    signal: controller.signal,
+    emitChunk: async () => undefined,
+    onInput: () => undefined,
+    frames: {
+      send: async (message) => {
+        outbound.push(JSON.parse(Buffer.from(message).toString("utf8")) as JsonRpcRecord);
+      },
+      onMessage: (listener) => {
+        receive = listener;
+        signalReady();
+        return () => {
+          if (receive === listener) {
+            receive = undefined;
+          }
+        };
+      },
+    },
+  };
+  return {
+    controller,
+    io,
+    outbound,
+    ready,
+    send: async (message: unknown) => {
+      if (!receive) {
+        throw new Error("Codex node command did not register a ready duplex receiver.");
+      }
+      await receive(Buffer.from(JSON.stringify(message)));
+    },
+    sendRaw: async (message: Uint8Array) => {
+      if (!receive) {
+        throw new Error("Codex node command did not register a ready duplex receiver.");
+      }
+      return await receive(message);
+    },
+  };
+}
+
+async function readNodeResponse(
+  frames: ReturnType<typeof createNodeFrames>,
+  id: number,
+): Promise<JsonRpcRecord> {
+  await vi.waitFor(() => expect(frames.outbound.some((message) => message.id === id)).toBe(true));
+  const response = frames.outbound.find((message) => message.id === id);
+  if (!response || response.error) {
+    throw new Error(`Codex exec-server request ${id} failed: ${JSON.stringify(response?.error)}`);
+  }
+  return response.result as JsonRpcRecord;
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("Codex paired-node exec-server", () => {
+  it("requires exact one-time approval before the dangerous explicit-allowlist command runs", async () => {
+    const policy = createCodexNodeExecServerInvokePolicy();
+    expect(policy.commands).toEqual([CODEX_NODE_EXEC_SERVER_COMMAND]);
+    expect(policy.dangerous).toBe(true);
+    expect(policy.defaultPlatforms).toBeUndefined();
+    expect(policy.classifyRisk?.({ command: CODEX_NODE_EXEC_SERVER_COMMAND, params: {} })).toEqual({
+      level: "high",
+      family: "codex.exec-server",
+    });
+
+    const invokeNode = vi.fn(async () => ({ ok: true as const, payload: { connected: true } }));
+    const request = vi.fn();
+    const { placement } = createManagedWorkspaceInvocation(process.cwd());
+    const context = {
+      nodeId: "paired-node",
+      command: CODEX_NODE_EXEC_SERVER_COMMAND,
+      params: placement,
+      config: {},
+      risk: { level: "high", family: "codex.exec-server" },
+      approvals: { request },
+      invokeNode,
+    } satisfies OpenClawPluginNodeInvokePolicyContext;
+
+    for (const decision of ["deny", "allow-always", null] as const) {
+      request.mockResolvedValueOnce({ decision });
+      await expect(policy.handle(context)).resolves.toMatchObject({
+        ok: false,
+        code: "CODEX_NODE_EXEC_APPROVAL_DENIED",
+      });
+      expect(invokeNode).not.toHaveBeenCalled();
+    }
+    await expect(policy.handle({ ...context, approvals: undefined })).resolves.toMatchObject({
+      ok: false,
+      code: "CODEX_NODE_EXEC_APPROVAL_REQUIRED",
+    });
+    expect(invokeNode).not.toHaveBeenCalled();
+
+    await expect(
+      policy.handle({ ...context, params: { cwd: process.cwd() } }),
+    ).resolves.toMatchObject({
+      ok: false,
+      code: "CODEX_NODE_EXEC_WORKSPACE_INVALID",
+    });
+    expect(invokeNode).not.toHaveBeenCalled();
+
+    const approvedPlacement = { ...placement };
+    request.mockImplementationOnce(async () => {
+      placement.cwd = path.parse(process.cwd()).root;
+      return { decision: "allow-once" };
+    });
+    await expect(policy.handle(context)).resolves.toEqual({
+      ok: true,
+      payload: { connected: true },
+    });
+    expect(invokeNode).toHaveBeenCalledOnce();
+    expect(invokeNode).toHaveBeenCalledWith({ params: approvedPlacement });
+    expect(request).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: "Run Codex execution on paired device",
+        description: expect.stringContaining(`paired-node: ${approvedPlacement.cwd}`),
+        severity: "critical",
+        allowedDecisions: ["allow-once"],
+      }),
+    );
+    expect(request.mock.lastCall?.[0].description).toContain(
+      "arbitrary processes and filesystem access across the paired-device account",
+    );
+  });
+
+  it("rejects unmanaged placement identities before launch and malformed or oversized frames", async () => {
+    const command = createCodexNodeExecServerCommand();
+    const frames = createNodeFrames();
+    const workspace = createManagedWorkspaceInvocation(process.cwd());
+    const encodedPlacement = JSON.stringify(workspace.placement);
+    await expect(command.handle(encodedPlacement)).rejects.toThrow("requires duplex frames");
+    await expect(
+      command.handle(
+        JSON.stringify({ ...workspace.placement, env: { TOKEN: "canary" } }),
+        frames.io,
+        workspace.context,
+      ),
+    ).rejects.toThrow("exact managed placement workspace");
+    await expect(command.handle(encodedPlacement, frames.io)).rejects.toThrow(
+      "active managed placement authority",
+    );
+    await expect(
+      command.handle(encodedPlacement, frames.io, {
+        ...workspace.context,
+        sessionKey: "agent:main:different-session",
+      }),
+    ).rejects.toThrow("active managed placement authority");
+    expect(workspace.acquireManagedWorkspace).not.toHaveBeenCalled();
+    for (const replacement of [
+      { cwd: path.parse(process.cwd()).root },
+      { environmentId: "other-environment" },
+      { sessionId: "other-session" },
+      { ownerEpoch: 2 },
+    ]) {
+      await expect(
+        command.handle(
+          JSON.stringify({ ...workspace.placement, ...replacement }),
+          frames.io,
+          workspace.context,
+        ),
+      ).rejects.toThrow("node placement does not own the requested workspace");
+    }
+    expect(workspace.release).not.toHaveBeenCalled();
+
+    const invocation = command.handle(encodedPlacement, frames.io, workspace.context);
+    void invocation.catch(() => {});
+    await Promise.race([frames.ready, invocation]);
+    await expect(frames.sendRaw(Buffer.from('{"id":1}\n{"id":2}'))).rejects.toThrow(
+      "exactly one message",
+    );
+    await expect(frames.sendRaw(Uint8Array.of(0xff, 0xfe))).rejects.toThrow("malformed UTF-8");
+    await expect(frames.sendRaw(new Uint8Array(64 * 1024 * 1024 + 1))).rejects.toThrow("64 MiB");
+    frames.controller.abort(new Error("malformed-frame fixture closed"));
+    await expect(invocation).rejects.toThrow("malformed-frame fixture closed");
+    expect(workspace.release).toHaveBeenCalledOnce();
+  });
+
+  it("relays the actual pinned Codex binary, isolates credentials, and removes its private home", async () => {
+    vi.stubEnv("OPENAI_API_KEY", "node-provider-canary");
+    vi.stubEnv("AWS_ACCESS_KEY_ID", "node-cloud-canary");
+    vi.stubEnv("GOOGLE_APPLICATION_CREDENTIALS", "/node-cloud-canary.json");
+    vi.stubEnv("GITHUB_TOKEN", "node-forge-canary");
+    vi.stubEnv("SSH_AUTH_SOCK", "/node-ssh-canary.sock");
+    vi.stubEnv("NODE_OPTIONS", "--no-warnings");
+
+    await withTempWorkspace(
+      { rootDir: resolvePreferredOpenClawTmpDir(), prefix: "codex-node-exec-contract-" },
+      async ({ dir }) => {
+        const cwd = await realpath(dir);
+        const workspaceUri = pathToFileURL(cwd).href;
+        const probePath = path.join(cwd, "probe.txt");
+        const probeUri = pathToFileURL(probePath).href;
+        const frames = createNodeFrames();
+        const command = createCodexNodeExecServerCommand();
+        const workspace = createManagedWorkspaceInvocation(cwd);
+        const invocation = command.handle(
+          JSON.stringify(workspace.placement),
+          frames.io,
+          workspace.context,
+        );
+        void invocation.catch(() => {});
+        let isolatedHome: string | undefined;
+
+        try {
+          await Promise.race([frames.ready, invocation]);
+          // Codex deliberately omits jsonrpc:"2.0" from every wire envelope.
+          await frames.send({
+            id: 1,
+            method: "initialize",
+            params: { clientName: "openclaw-node" },
+          });
+          expect(await readNodeResponse(frames, 1)).toMatchObject({
+            sessionId: expect.any(String),
+          });
+          await frames.send({ method: "initialized", params: {} });
+
+          await frames.send({ id: 2, method: "environment/info", params: {} });
+          expect(await readNodeResponse(frames, 2)).toMatchObject({
+            cwd: workspaceUri,
+            capabilities: { networkProxyLaunch: true, sandboxedFileStreaming: true },
+          });
+
+          const dataBase64 = Buffer.from("node filesystem proof\n").toString("base64");
+          await frames.send({
+            id: 3,
+            method: "fs/writeFile",
+            params: { path: probeUri, dataBase64, sandbox: null },
+          });
+          expect(await readNodeResponse(frames, 3)).toEqual({});
+          expect(await readFile(probePath, "utf8")).toBe("node filesystem proof\n");
+
+          await frames.send({
+            id: 4,
+            method: "fs/canonicalize",
+            params: { path: probeUri, sandbox: null },
+          });
+          expect(await readNodeResponse(frames, 4)).toEqual({ path: probeUri });
+          await frames.send({
+            id: 5,
+            method: "fs/open",
+            params: { handleId: "node-proof", path: probeUri, sandbox: null },
+          });
+          expect(await readNodeResponse(frames, 5)).toEqual({ handleId: "node-proof" });
+          await frames.send({
+            id: 6,
+            method: "fs/readBlock",
+            params: { handleId: "node-proof", offset: 0, len: 256 },
+          });
+          expect(await readNodeResponse(frames, 6)).toEqual({ chunk: dataBase64, eof: true });
+          await frames.send({ id: 7, method: "fs/close", params: { handleId: "node-proof" } });
+          expect(await readNodeResponse(frames, 7)).toEqual({});
+
+          const script = [
+            "process.stdin.once('data', input => {",
+            "process.stdout.write(JSON.stringify({",
+            "input: input.toString().trim(),",
+            "ordinary: process.env.NODE_EXEC_ORDINARY ?? null,",
+            "home: process.env.HOME ?? null,",
+            "codexHome: process.env.CODEX_HOME ?? null,",
+            "userProfile: process.env.USERPROFILE ?? null,",
+            "provider: process.env.OPENAI_API_KEY ?? null,",
+            "cloud: process.env.AWS_ACCESS_KEY_ID ?? null,",
+            "cloudFile: process.env.GOOGLE_APPLICATION_CREDENTIALS ?? null,",
+            "forge: process.env.GITHUB_TOKEN ?? null,",
+            "ssh: process.env.SSH_AUTH_SOCK ?? null,",
+            "injection: process.env.NODE_OPTIONS ?? null",
+            "}) + '\\n', () => process.exit(0))",
+            "})",
+          ].join("\n");
+          await frames.send({
+            id: 8,
+            method: "process/start",
+            params: {
+              processId: "node-proof",
+              argv: [process.execPath, "-e", script],
+              cwd: workspaceUri,
+              env: { NODE_EXEC_ORDINARY: "visible" },
+              envPolicy: {
+                inherit: "all",
+                ignoreDefaultExcludes: true,
+                exclude: [],
+                set: {},
+                includeOnly: [],
+              },
+              tty: false,
+              pipeStdin: true,
+              arg0: null,
+            },
+          });
+          expect(await readNodeResponse(frames, 8)).toMatchObject({ processId: "node-proof" });
+          await frames.send({
+            id: 9,
+            method: "process/write",
+            params: {
+              processId: "node-proof",
+              chunk: Buffer.from("node carrier\n").toString("base64"),
+              writeId: "node-proof-write",
+            },
+          });
+          await readNodeResponse(frames, 9);
+          await vi.waitFor(() =>
+            expect(frames.outbound.some((message) => message.method === "process/closed")).toBe(
+              true,
+            ),
+          );
+          const notifications = frames.outbound.filter((message) =>
+            String(message.method).startsWith("process/"),
+          );
+          expect(notifications.map((message) => message.method)).toEqual([
+            "process/output",
+            "process/exited",
+            "process/closed",
+          ]);
+          const output = notifications[0]?.params as { chunk: string; seq: number };
+          const observed = JSON.parse(Buffer.from(output.chunk, "base64").toString("utf8")) as {
+            input: string;
+            ordinary: string;
+            home: string;
+            codexHome: string;
+            userProfile: string | null;
+            provider: string | null;
+            cloud: string | null;
+            cloudFile: string | null;
+            forge: string | null;
+            ssh: string | null;
+            injection: string | null;
+          };
+          expect(observed).toMatchObject({
+            input: "node carrier",
+            ordinary: "visible",
+            provider: null,
+            cloud: null,
+            cloudFile: null,
+            forge: null,
+            ssh: null,
+            injection: null,
+          });
+          expect(observed.codexHome).toBe(path.join(observed.home, ".codex"));
+          expect(observed.home).not.toBe(process.env.HOME);
+          if (process.platform === "win32") {
+            expect(observed.userProfile).toBe(observed.home);
+          }
+          isolatedHome = observed.home;
+
+          // A response spanning many pipe chunks must arrive as one intact frame.
+          const chunkedUri = pathToFileURL(path.join(cwd, "chunked.txt")).href;
+          const chunkedDataBase64 = Buffer.alloc(256 * 1024, 0x61).toString("base64");
+          await frames.send({
+            id: 10,
+            method: "fs/writeFile",
+            params: { path: chunkedUri, dataBase64: chunkedDataBase64, sandbox: null },
+          });
+          expect(await readNodeResponse(frames, 10)).toEqual({});
+          await frames.send({
+            id: 11,
+            method: "fs/readFile",
+            params: { path: chunkedUri, sandbox: null },
+          });
+          expect(await readNodeResponse(frames, 11)).toEqual({ dataBase64: chunkedDataBase64 });
+
+          await frames.send({ id: 12, method: "environment/status", params: {} });
+          expect(await readNodeResponse(frames, 12)).toEqual({ status: "ready" });
+          await frames.send({
+            id: 13,
+            method: "fs/walk",
+            params: {
+              path: workspaceUri,
+              options: {
+                maxDepth: 2,
+                maxDirectories: 10,
+                maxEntries: 30,
+                followDirectorySymlinks: false,
+                pruneHiddenDirectories: false,
+              },
+              sandbox: null,
+            },
+          });
+          expect(await readNodeResponse(frames, 13)).toMatchObject({
+            entries: expect.arrayContaining([
+              expect.objectContaining({ path: probeUri, kind: "file" }),
+              expect.objectContaining({ path: chunkedUri, kind: "file" }),
+            ]),
+            errors: [],
+            truncated: false,
+          });
+          await frames.send({
+            id: 14,
+            method: "capabilityRoots/discoverV1",
+            params: { roots: [{ id: "workspace", path: workspaceUri, sandbox: null }] },
+          });
+          expect(await readNodeResponse(frames, 14)).toMatchObject({
+            roots: [expect.objectContaining({ id: "workspace", path: workspaceUri })],
+          });
+
+          for (const control of [
+            { id: 15, processId: "node-signal", method: "process/signal", result: {} },
+            {
+              id: 17,
+              processId: "node-terminate",
+              method: "process/terminate",
+              result: { running: true },
+            },
+          ]) {
+            await frames.send({
+              id: control.id,
+              method: "process/start",
+              params: {
+                processId: control.processId,
+                argv: [process.execPath, "-e", "setInterval(() => {}, 60_000)"],
+                cwd: workspaceUri,
+                env: {},
+                tty: false,
+                pipeStdin: false,
+                arg0: null,
+              },
+            });
+            expect(await readNodeResponse(frames, control.id)).toMatchObject({
+              processId: control.processId,
+            });
+            await frames.send({
+              id: control.id + 1,
+              method: control.method,
+              params: {
+                processId: control.processId,
+                ...(control.method === "process/signal" ? { signal: "interrupt" } : {}),
+              },
+            });
+            expect(await readNodeResponse(frames, control.id + 1)).toEqual(control.result);
+            await vi.waitFor(() =>
+              expect(
+                frames.outbound.some(
+                  (message) =>
+                    message.method === "process/closed" &&
+                    (message.params as { processId?: string }).processId === control.processId,
+                ),
+              ).toBe(true),
+            );
+            expect(
+              frames.outbound
+                .filter(
+                  (message) =>
+                    String(message.method).startsWith("process/") &&
+                    (message.params as { processId?: string }).processId === control.processId,
+                )
+                .map((message) => message.method),
+            ).toEqual(["process/exited", "process/closed"]);
+          }
+
+          const httpServer = createServer((_request, response) => {
+            response.writeHead(200, { "content-type": "text/plain" });
+            response.write("alpha");
+            setImmediate(() => response.end("beta"));
+          });
+          httpServer.listen(0, "127.0.0.1");
+          try {
+            await once(httpServer, "listening");
+            const address = httpServer.address();
+            if (!address || typeof address === "string") {
+              throw new Error("Codex exec-server HTTP fixture did not bind a TCP port.");
+            }
+            await frames.send({
+              id: 19,
+              method: "http/request",
+              params: {
+                method: "GET",
+                url: `http://127.0.0.1:${address.port}/`,
+                headers: [],
+                bodyBase64: null,
+                timeoutMs: 3_000,
+                redirectPolicy: "follow",
+                requestId: "node-http-proof",
+                streamResponse: true,
+              },
+            });
+            expect(await readNodeResponse(frames, 19)).toMatchObject({
+              status: 200,
+              bodyBase64: "",
+            });
+            await vi.waitFor(() =>
+              expect(
+                frames.outbound.some(
+                  (message) =>
+                    message.method === "http/request/bodyDelta" &&
+                    (message.params as { requestId?: string; done?: boolean }).requestId ===
+                      "node-http-proof" &&
+                    (message.params as { done?: boolean }).done === true,
+                ),
+              ).toBe(true),
+            );
+            const chunks = frames.outbound
+              .filter(
+                (message) =>
+                  message.method === "http/request/bodyDelta" &&
+                  (message.params as { requestId?: string }).requestId === "node-http-proof",
+              )
+              .map(
+                (message) => message.params as { seq: number; deltaBase64: string; done: boolean },
+              );
+            expect(chunks.map((chunk) => chunk.seq)).toEqual(
+              chunks.map((_chunk, index) => index + 1),
+            );
+            expect(
+              Buffer.concat(
+                chunks.map((chunk) => Buffer.from(chunk.deltaBase64, "base64")),
+              ).toString("utf8"),
+            ).toBe("alphabeta");
+            expect(chunks.at(-1)?.done).toBe(true);
+          } finally {
+            await new Promise<void>((resolve, reject) => {
+              httpServer.close((error) => (error ? reject(error) : resolve()));
+            });
+          }
+
+          const policyScript = [
+            "const net = require('node:net')",
+            "const proxy = new URL(process.env.HTTP_PROXY)",
+            "const socket = net.connect(Number(proxy.port), proxy.hostname, () => {",
+            "socket.write('CONNECT 8.8.8.8:443 HTTP/1.1\\r\\nHost: 8.8.8.8:443\\r\\n\\r\\n')",
+            "})",
+            "socket.once('data', chunk => {",
+            "const line = chunk.toString().split('\\r\\n')[0]",
+            "process.stdout.write(line + '\\n', () => { socket.end(); process.exit(0) })",
+            "})",
+          ].join("\n");
+          await frames.send({
+            id: 20,
+            method: "process/start",
+            params: {
+              processId: "node-policy",
+              argv: [process.execPath, "-e", policyScript],
+              cwd: workspaceUri,
+              env: {},
+              tty: false,
+              pipeStdin: false,
+              arg0: null,
+              networkProxy: {
+                proxy: {
+                  enabled: true,
+                  enableSocks5: false,
+                  enableSocks5Udp: false,
+                  allowUpstreamProxy: false,
+                  dangerouslyAllowAllUnixSockets: false,
+                  mode: "full",
+                  domains: null,
+                  unixSockets: null,
+                  allowLocalBinding: false,
+                },
+                environmentId: "node-policy-environment",
+                executionId: "node-policy-execution",
+                policyDecisionTimeoutMs: 3_000,
+              },
+            },
+          });
+          expect(await readNodeResponse(frames, 20)).toMatchObject({ processId: "node-policy" });
+          await vi.waitFor(() =>
+            expect(
+              frames.outbound.some((message) => message.method === "network/policyRequest"),
+            ).toBe(true),
+          );
+          const policyRequest = frames.outbound.find(
+            (message) => message.method === "network/policyRequest",
+          );
+          expect(policyRequest).toMatchObject({
+            id: expect.any(Number),
+            params: {
+              processId: "node-policy",
+              request: { protocol: "https_connect", host: "8.8.8.8", port: 443 },
+            },
+          });
+          await frames.send({
+            id: policyRequest?.id,
+            result: { decision: { type: "deny", reason: "node-policy-proof" } },
+          });
+          await vi.waitFor(() =>
+            expect(
+              frames.outbound.some(
+                (message) =>
+                  message.method === "process/closed" &&
+                  (message.params as { processId?: string }).processId === "node-policy",
+              ),
+            ).toBe(true),
+          );
+          expect(frames.outbound).toEqual(
+            expect.arrayContaining([
+              expect.objectContaining({ method: "network/policyDecision" }),
+              expect.objectContaining({
+                method: "process/output",
+                params: expect.objectContaining({
+                  processId: "node-policy",
+                  chunk: Buffer.from("HTTP/1.1 403 Forbidden\n").toString("base64"),
+                }),
+              }),
+            ]),
+          );
+        } finally {
+          frames.controller.abort(new Error("paired-device attempt completed"));
+          await expect(invocation).rejects.toThrow("paired-device attempt completed");
+          await command.onDisconnect?.();
+          expect(workspace.release).toHaveBeenCalledOnce();
+        }
+
+        expect(isolatedHome).toEqual(expect.any(String));
+        await expect(access(isolatedHome!)).rejects.toMatchObject({ code: "ENOENT" });
+      },
+    );
+  });
+});
diff --git a/extensions/codex/src/node-exec-server.ts b/extensions/codex/src/node-exec-server.ts
new file mode 100644
index 000000000000..45dc02b0906b
--- /dev/null
+++ b/extensions/codex/src/node-exec-server.ts
@@ -0,0 +1,148 @@
+/** Declares the explicitly approved, lazily loaded paired-node Codex exec-server. */
+import type {
+  OpenClawPluginNodeHostCommand,
+  OpenClawPluginNodeInvokePolicy,
+} from "openclaw/plugin-sdk/plugin-entry";
+import { isRecord } from "openclaw/plugin-sdk/string-coerce-runtime";
+
+const CODEX_NODE_EXEC_SERVER_COMMAND = "codex.exec-server.stdio.v1";
+
+const CODEX_NODE_EXEC_SERVER_CAPABILITY = "codex.exec-server";
+
+function parseCodexNodePlacementWorkspace(value: unknown) {
+  if (
+    !isRecord(value) ||
+    Object.keys(value).length !== 5 ||
+    typeof value.cwd !== "string" ||
+    !value.cwd.trim() ||
+    value.cwd.includes("\0") ||
+    typeof value.environmentId !== "string" ||
+    typeof value.sessionId !== "string" ||
+    ![value.environmentId, value.sessionId].every(
+      (identifier) =>
+        identifier.length > 0 &&
+        identifier.length <= 256 &&
+        identifier.trim() === identifier &&
+        !identifier.includes("\0"),
+    ) ||
+    typeof value.sessionKey !== "string" ||
+    !value.sessionKey ||
+    value.sessionKey.trim() !== value.sessionKey ||
+    value.sessionKey.includes("\0") ||
+    typeof value.ownerEpoch !== "number" ||
+    !Number.isSafeInteger(value.ownerEpoch) ||
+    value.ownerEpoch < 1
+  ) {
+    throw new Error("Codex node exec-server requires an exact managed placement workspace.");
+  }
+  return {
+    cwd: value.cwd,
+    environmentId: value.environmentId,
+    sessionId: value.sessionId,
+    ownerEpoch: value.ownerEpoch,
+    sessionKey: value.sessionKey,
+  };
+}
+
+/** Registers the exact pinned exec-server as an explicitly approved duplex node command. */
+export function createCodexNodeExecServerCommand(): OpenClawPluginNodeHostCommand {
+  const activeProcesses = new Set<() => Promise<void>>();
+  return {
+    command: CODEX_NODE_EXEC_SERVER_COMMAND,
+    cap: CODEX_NODE_EXEC_SERVER_CAPABILITY,
+    dangerous: true,
+    duplex: true,
+    onDisconnect: async () => {
+      await Promise.all([...activeProcesses].map(async (terminate) => await terminate()));
+    },
+    handle: async (paramsJSON, io, context) => {
+      if (!io?.frames) {
+        throw new Error("Codex node exec-server requires duplex frames.");
+      }
+      let request: unknown;
+      try {
+        request = JSON.parse(paramsJSON ?? "null") as unknown;
+      } catch {
+        throw new Error("Codex node exec-server requires a valid workspace request.");
+      }
+      const placement = parseCodexNodePlacementWorkspace(request);
+      if (
+        !context?.acquireManagedWorkspace ||
+        context.sessionKey !== placement.sessionKey ||
+        io.signal.aborted
+      ) {
+        throw new Error("Codex node exec-server requires active managed placement authority.");
+      }
+      const workspace = context.acquireManagedWorkspace({
+        workspaceDir: placement.cwd,
+        environmentId: placement.environmentId,
+        sessionId: placement.sessionId,
+        ownerEpoch: placement.ownerEpoch,
+        sessionKey: placement.sessionKey,
+      });
+      const frames = io.frames;
+      let unsubscribe: (() => void) | undefined;
+      try {
+        const { runCodexNodeExecServer } = await import("./node-exec-server.runtime.js");
+        return await runCodexNodeExecServer({
+          workspaceDir: workspace.workspaceDir,
+          io,
+          activeProcesses,
+          // Listener registration announces readiness, so the child must own it first.
+          onFrameReceiver: (receiver) => {
+            unsubscribe = frames.onMessage(receiver);
+          },
+        });
+      } finally {
+        try {
+          unsubscribe?.();
+        } finally {
+          workspace.release();
+        }
+      }
+    },
+  };
+}
+
+/** Keeps paired-device exec-server launch behind explicit arming and one-time approval. */
+export function createCodexNodeExecServerInvokePolicy(): OpenClawPluginNodeInvokePolicy {
+  return {
+    commands: [CODEX_NODE_EXEC_SERVER_COMMAND],
+    dangerous: true,
+    classifyRisk: () => ({ level: "high", family: CODEX_NODE_EXEC_SERVER_CAPABILITY }),
+    handle: async (context) => {
+      if (!context.approvals || context.risk?.level !== "high") {
+        return {
+          ok: false,
+          code: "CODEX_NODE_EXEC_APPROVAL_REQUIRED",
+          message: "Codex paired-device execution requires an available approval reviewer.",
+        };
+      }
+      let placement: ReturnType<typeof parseCodexNodePlacementWorkspace>;
+      try {
+        placement = parseCodexNodePlacementWorkspace(context.params);
+      } catch {
+        return {
+          ok: false,
+          code: "CODEX_NODE_EXEC_WORKSPACE_INVALID",
+          message: "Codex paired-device execution requires an exact managed placement workspace.",
+        };
+      }
+      const deviceName = context.node?.displayName ?? context.nodeId;
+      const approval = await context.approvals.request({
+        title: "Run Codex execution on paired device",
+        description: `${deviceName}: ${placement.cwd}; allows arbitrary processes and filesystem access across the paired-device account, not only this workspace.`,
+        severity: "critical",
+        allowedDecisions: ["allow-once"],
+      });
+      if (approval.decision !== "allow-once") {
+        return {
+          ok: false,
+          code: "CODEX_NODE_EXEC_APPROVAL_DENIED",
+          message: "Codex paired-device execution requires one-time approval.",
+        };
+      }
+      return await context.invokeNode({ params: placement });
+    },
+  };
+}
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 70a5515c88a2..1873fc32ea4a 100644
--- a/packages/gateway-protocol/src/schema/agents-models-skills.test.ts
+++ b/packages/gateway-protocol/src/schema/agents-models-skills.test.ts
@@ -271,7 +271,11 @@ describe("ModelsListResultSchema", () => {
         fallback: "openclaw",
         cloudPlacementSupported: true,
         cloudPlacementExecutionMode: "remote-exec",
-        devicePlacementSupported: false,
+        devicePlacementSupported: true,
+        devicePlacement: {
+          requiredNodeCommands: ["runtime.exec-server.v1"],
+          consumesWorkerSlot: false,
+        },
         source: "model",
       },
       thinkingLevels: [
@@ -301,6 +305,48 @@ describe("ModelsListResultSchema", () => {
       {
         models: [{ ...model, agentRuntime: { id: "codex", source: "unknown" } }],
       },
+      {
+        models: [
+          {
+            ...model,
+            agentRuntime: {
+              ...model.agentRuntime,
+              devicePlacement: { requiredNodeCommands: ["runtime.exec-server.v1"] },
+            },
+          },
+        ],
+      },
+      {
+        models: [
+          {
+            ...model,
+            agentRuntime: {
+              ...model.agentRuntime,
+              devicePlacement: {
+                requiredNodeCommands: ["x".repeat(129)],
+                consumesWorkerSlot: false,
+              },
+            },
+          },
+        ],
+      },
+      {
+        models: [
+          {
+            ...model,
+            agentRuntime: {
+              ...model.agentRuntime,
+              devicePlacement: {
+                requiredNodeCommands: Array.from(
+                  { length: 33 },
+                  (_, index) => `runtime.${index}.v1`,
+                ),
+                consumesWorkerSlot: false,
+              },
+            },
+          },
+        ],
+      },
       { models: [{ ...model, thinkingLevels: [{ id: "", label: "Off" }] }] },
       { models: [{ ...model, input: ["text", "binary"] }] },
       { models: [], providerOutcomes: [{ provider: "openai", status: "unknown" }] },
diff --git a/packages/gateway-protocol/src/schema/agents-models-skills.ts b/packages/gateway-protocol/src/schema/agents-models-skills.ts
index 1ce9a589951f..6fc38c1f6f44 100644
--- a/packages/gateway-protocol/src/schema/agents-models-skills.ts
+++ b/packages/gateway-protocol/src/schema/agents-models-skills.ts
@@ -21,6 +21,15 @@ const GatewayAgentRuntimeSchema = closedObject({
   fallback: Type.Optional(Type.Union([Type.Literal("openclaw"), Type.Literal("none")])),
   cloudPlacementSupported: Type.Optional(Type.Boolean()),
   cloudPlacementExecutionMode: Type.Optional(WorkerExecutionModeSchema),
+  devicePlacement: Type.Optional(
+    closedObject({
+      requiredNodeCommands: Type.Array(Type.String({ minLength: 1, maxLength: 128 }), {
+        maxItems: 32,
+        uniqueItems: true,
+      }),
+      consumesWorkerSlot: Type.Boolean(),
+    }),
+  ),
   devicePlacementSupported: Type.Optional(Type.Boolean()),
   source: Type.Union([
     Type.Literal("env"),
diff --git a/packages/gateway-protocol/src/schema/environments.test.ts b/packages/gateway-protocol/src/schema/environments.test.ts
index 906b434a9524..386a91c5488f 100644
--- a/packages/gateway-protocol/src/schema/environments.test.ts
+++ b/packages/gateway-protocol/src/schema/environments.test.ts
@@ -176,6 +176,31 @@ describe("worker environment protocol schemas", () => {
     ).toBe(false);
   });
 
+  it("accepts only bounded, unique effective node command authority", () => {
+    const node = {
+      id: "node:build-mac",
+      type: "node",
+      status: "available",
+    };
+
+    expect(
+      Value.Check(EnvironmentSummarySchema, {
+        ...node,
+        invocableCommands: ["codex.exec-server.stdio.v1", "system.run"],
+      }),
+    ).toBe(true);
+    expect(Value.Check(EnvironmentSummarySchema, { ...node, invocableCommands: [] })).toBe(true);
+
+    for (const invocableCommands of [
+      [""],
+      ["system.run", "system.run"],
+      ["x".repeat(129)],
+      Array.from({ length: 129 }, (_, index) => `command.${index}`),
+    ]) {
+      expect(Value.Check(EnvironmentSummarySchema, { ...node, invocableCommands })).toBe(false);
+    }
+  });
+
   it("accepts bounded node lifecycle history and rejects malformed timestamps", () => {
     const node = {
       id: "node:build-mac",
diff --git a/packages/gateway-protocol/src/schema/environments.ts b/packages/gateway-protocol/src/schema/environments.ts
index 1c6f9279fbd5..3c2688f1ca53 100644
--- a/packages/gateway-protocol/src/schema/environments.ts
+++ b/packages/gateway-protocol/src/schema/environments.ts
@@ -102,6 +102,12 @@ function createEnvironmentSummarySchema() {
     lastSeenReason: Type.Optional(NonEmptyString),
     trust: Type.Optional(EnvironmentTrustSchema),
     capabilities: Type.Optional(Type.Array(NonEmptyString)),
+    invocableCommands: Type.Optional(
+      Type.Array(Type.String({ minLength: 1, maxLength: 128 }), {
+        maxItems: 128,
+        uniqueItems: true,
+      }),
+    ),
     desktop: Type.Optional(Type.Boolean()),
     issues: Type.Optional(Type.Array(RuntimeTargetIssueSchema, { minItems: 1, maxItems: 8 })),
     worker: Type.Optional(WorkerEnvironmentMetadataSchema),
diff --git a/src/agents/agent-tools.construction-routing.test.ts b/src/agents/agent-tools.construction-routing.test.ts
index cd967df78dd8..f3d51ad5f451 100644
--- a/src/agents/agent-tools.construction-routing.test.ts
+++ b/src/agents/agent-tools.construction-routing.test.ts
@@ -37,6 +37,7 @@ vi.mock("./openclaw-tools.js", async (importOriginal) => {
 import "./test-helpers/fast-bash-tools.js";
 import "./test-helpers/fast-coding-tools.js";
 import { createOpenClawCodingTools } from "./agent-tools.js";
+import { createAgentToolsSandboxContext } from "./test-helpers/agent-tools-sandbox-context.js";
 import { AUTOMATIONS_TOOL_NAME } from "./tools/automations-tool-name.js";
 
 function firstOpenClawToolsOptions(): { cronSelfRemoveOnlyJobId?: string } | undefined {
@@ -114,3 +115,42 @@ describe("createOpenClawCodingTools exec notification routing", () => {
     );
   });
 });
+
+describe("createOpenClawCodingTools sandbox filesystem ownership", () => {
+  const sandbox = createAgentToolsSandboxContext({ workspaceDir: "/managed/workspace" });
+
+  it("keeps host-owned tools available when no sandbox filesystem family is requested", () => {
+    mocks.createOpenClawToolsOptions.mockClear();
+
+    const tools = createOpenClawCodingTools({
+      sandbox,
+      toolConstructionPlan: {
+        includeBaseCodingTools: false,
+        includeShellTools: false,
+        includeChannelTools: false,
+        includeOpenClawTools: true,
+        includePluginTools: true,
+      },
+    });
+
+    expect(tools.map((tool) => tool.name)).toContain(AUTOMATIONS_TOOL_NAME);
+    expect(mocks.createOpenClawToolsOptions).toHaveBeenCalledOnce();
+  });
+
+  it.each([
+    { includeBaseCodingTools: true, includeShellTools: false },
+    { includeBaseCodingTools: false, includeShellTools: true },
+  ])("rejects sandbox filesystem families without their bridge: %o", (families) => {
+    expect(() =>
+      createOpenClawCodingTools({
+        sandbox,
+        toolConstructionPlan: {
+          ...families,
+          includeChannelTools: false,
+          includeOpenClawTools: false,
+          includePluginTools: false,
+        },
+      }),
+    ).toThrow("Sandbox filesystem bridge is unavailable.");
+  });
+});
diff --git a/src/agents/agent-tools.ts b/src/agents/agent-tools.ts
index 59f0c5e5a3d6..acc44f9b79ba 100644
--- a/src/agents/agent-tools.ts
+++ b/src/agents/agent-tools.ts
@@ -983,8 +983,8 @@ function createOpenClawCodingToolsInternal(options?: OpenClawCodingToolsOptions)
     workspaceDir: workspaceRoot,
     ...(options?.skillsSnapshot ? { skillsSnapshot: options.skillsSnapshot } : {}),
     ...(options?.skillUsagePaths ? { skillUsagePaths: options.skillUsagePaths } : {}),
-    ...(sandboxRoot && allowWorkspaceWrites
-      ? { sandbox: { root: sandboxRoot, bridge: sandboxFsBridge! } }
+    ...(sandboxRoot && sandboxFsBridge && allowWorkspaceWrites
+      ? { sandbox: { root: sandboxRoot, bridge: sandboxFsBridge } }
       : {}),
     sessionKey: options?.sessionKey,
     sessionId: options?.sessionId,
diff --git a/src/agents/core-coding-tools.ts b/src/agents/core-coding-tools.ts
index 62a7ac3946a7..9e0d5d6e84a3 100644
--- a/src/agents/core-coding-tools.ts
+++ b/src/agents/core-coding-tools.ts
@@ -112,7 +112,11 @@ export function createCoreCodingTools(options: CoreCodingToolsOptions): AnyAgent
   const sandboxRoot = sandbox?.workspaceDir;
   const sandboxFsBridge = sandbox?.fsBridge;
   const allowWorkspaceWrites = sandbox?.workspaceAccess !== "ro";
-  if (sandboxRoot && !sandboxFsBridge) {
+  if (
+    sandboxRoot &&
+    !sandboxFsBridge &&
+    (options.includeBaseCodingTools || options.includeShellTools)
+  ) {
     throw new Error("Sandbox filesystem bridge is unavailable.");
   }
 
diff --git a/src/agents/harness/types.ts b/src/agents/harness/types.ts
index e90306777f67..dea27d9d42a5 100644
--- a/src/agents/harness/types.ts
+++ b/src/agents/harness/types.ts
@@ -343,6 +343,12 @@ export type AgentHarnessDeliveryDefaults = {
   sourceVisibleReplies?: "automatic" | "message_tool";
 };
 
+/** Exact node authority and worker capacity required by one paired-device runtime. */
+export type DevicePlacementRequirement = {
+  requiredNodeCommands: readonly string[];
+  consumesWorkerSlot: boolean;
+};
+
 type AgentHarnessRunCapability<
   TAttemptParams extends AgentHarnessAttemptParams = AgentHarnessAttemptParams,
 > = {
@@ -354,6 +360,8 @@ type AgentHarnessRunCapability<
    * dynamic probing; an empty list marks an explicit-only harness.
    */
   autoSelection?: { providerIds: readonly string[] };
+  /** Declares host-owned remote execution and its exact paired-device requirements. */
+  cloudPlacement?: { mode: "remote-exec"; devicePlacement?: DevicePlacementRequirement };
   /**
    * Plugin ids this harness owner permits to execute its locked sessions.
    * Delegates receive work admission and execution only; session mutation stays owner-only.
diff --git a/src/commands/doctor-node-hosting-preconditions.test.ts b/src/commands/doctor-node-hosting-preconditions.test.ts
index 08676114b749..b2b33469a5a5 100644
--- a/src/commands/doctor-node-hosting-preconditions.test.ts
+++ b/src/commands/doctor-node-hosting-preconditions.test.ts
@@ -1,13 +1,68 @@
 // Doctor node-hosting precondition tests cover browser-only auth and unreachable onboarding.
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { registerAgentHarness } from "../agents/harness/registry.js";
+import type { AgentHarness } from "../agents/harness/types.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
+import { createEmptyPluginRegistry } from "../plugins/registry-empty.js";
+import {
+  getActivePluginRegistry,
+  resetPluginRuntimeStateForTest,
+  setActivePluginRegistry,
+} from "../plugins/runtime.js";
 import { collectNodeHostingPreconditionFindings } from "./doctor-node-hosting-preconditions.js";
 
+const originalPluginRegistry = getActivePluginRegistry();
+
 function findingsFor(cfg: OpenClawConfig) {
   return collectNodeHostingPreconditionFindings(cfg);
 }
 
 describe("node-hosting preconditions", () => {
+  beforeEach(() => {
+    setActivePluginRegistry(
+      createEmptyPluginRegistry(),
+      "node-hosting-preconditions-test",
+      "default",
+    );
+    for (const [id, cloudPlacement] of [
+      [
+        "codex",
+        {
+          mode: "remote-exec",
+          devicePlacement: {
+            requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+            consumesWorkerSlot: false,
+          },
+        },
+      ],
+      ["cloud-only", { mode: "remote-exec" }],
+      ["acpx", undefined],
+    ] as const) {
+      const harness: AgentHarness = {
+        id,
+        label: id,
+        ...(cloudPlacement ? { cloudPlacement } : {}),
+        supports: () => ({ supported: true }),
+        async runAttempt() {
+          throw new Error("not used");
+        },
+      };
+      registerAgentHarness(harness);
+    }
+  });
+
+  afterEach(() => {
+    if (originalPluginRegistry) {
+      setActivePluginRegistry(
+        originalPluginRegistry,
+        "node-hosting-preconditions-test-restore",
+        "default",
+      );
+      return;
+    }
+    resetPluginRuntimeStateForTest();
+  });
+
   const healthyBase = {
     gateway: {
       bind: "lan",
@@ -91,7 +146,7 @@ describe("node-hosting preconditions", () => {
       requirement: "node-onboarding-plugin",
     },
     {
-      name: "every configured agent resolves to an external runtime",
+      name: "every configured agent resolves to an incompatible runtime",
       cfg: {
         ...healthyBase,
         agents: {
@@ -99,7 +154,7 @@ describe("node-hosting preconditions", () => {
           entries: {
             writer: {
               model: "openai/gpt-5.6-sol",
-              models: { "openai/gpt-5.6-sol": { agentRuntime: { id: "codex" } } },
+              models: { "openai/gpt-5.6-sol": { agentRuntime: { id: "cloud-only" } } },
             },
             reviewer: {
               model: "anthropic/claude-sonnet-4-6",
@@ -140,6 +195,37 @@ describe("node-hosting preconditions", () => {
     ).toEqual([]);
   });
 
+  it("accepts a registered external runtime that declares paired-device support", () => {
+    expect(
+      findingsFor({
+        ...healthyBase,
+        agents: {
+          defaults: {
+            model: "openai/gpt-5.6-sol",
+            models: { "openai/gpt-5.6-sol": { agentRuntime: { id: "codex" } } },
+          },
+        },
+      }),
+    ).toEqual([]);
+  });
+
+  it("does not activate plugins or reject an unknown external runtime", () => {
+    resetPluginRuntimeStateForTest();
+
+    expect(
+      findingsFor({
+        ...healthyBase,
+        agents: {
+          defaults: {
+            model: "openai/gpt-5.6-sol",
+            models: { "openai/gpt-5.6-sol": { agentRuntime: { id: "codex" } } },
+          },
+        },
+      }),
+    ).toEqual([]);
+    expect(getActivePluginRegistry()).toBeNull();
+  });
+
   it("gives verbatim onboarding and device-runtime remediation", () => {
     const findings = findingsFor({
       ...healthyBase,
@@ -147,7 +233,7 @@ describe("node-hosting preconditions", () => {
       agents: {
         defaults: {
           model: "openai/gpt-5.6-sol",
-          models: { "openai/gpt-5.6-sol": { agentRuntime: { id: "codex" } } },
+          models: { "openai/gpt-5.6-sol": { agentRuntime: { id: "cloud-only" } } },
         },
       },
     });
@@ -160,7 +246,7 @@ describe("node-hosting preconditions", () => {
     expect(
       findings.find((finding) => finding.requirement === "device-session-runtime")?.fixHint,
     ).toBe(
-      'Set agentRuntime.id: "openclaw" on at least one provider/model route (models.providers.<provider>.agentRuntime, agents.defaults.models["provider/model"].agentRuntime, or agents.entries.<id>.models["provider/model"].agentRuntime), then select that agent/model for paired-device sessions. Runtime policy is model/provider-scoped; whole-agent runtime keys are ignored. For a multi-agent roster, set agents.ownership: "explicit".',
+      'Select an agent/model route whose runtime supports paired-device placement, then ensure its plugin is enabled and its required node commands are explicitly allowed. Runtime policy is model/provider-scoped; whole-agent runtime keys are ignored. For a multi-agent roster, set agents.ownership: "explicit".',
     );
   });
 
diff --git a/src/commands/doctor-node-hosting-preconditions.ts b/src/commands/doctor-node-hosting-preconditions.ts
index f1161f09130d..963aca9a2b81 100644
--- a/src/commands/doctor-node-hosting-preconditions.ts
+++ b/src/commands/doctor-node-hosting-preconditions.ts
@@ -9,6 +9,7 @@ import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { HealthFinding } from "../flows/health-checks.js";
 import { hasConfiguredGatewayAuthSecretInput } from "../gateway/auth-config-utils.js";
 import { normalizePluginsConfig, resolveEffectiveEnableState } from "../plugins/config-state.js";
+import { getActivePluginRegistry } from "../plugins/runtime.js";
 
 const CHECK_ID = "core/doctor/node-hosting-preconditions";
 const LOOPBACK_JOIN_CODE_MESSAGE =
@@ -57,17 +58,22 @@ function lacksNodeOnboardingPlugin(cfg: OpenClawConfig): boolean {
   }).enabled;
 }
 
-function lacksEmbeddedRuntimeRoute(cfg: OpenClawConfig): boolean {
+function lacksDeviceCapableRuntimeRoute(cfg: OpenClawConfig): boolean {
+  const registry = getActivePluginRegistry();
   return listAgentIds(cfg).every((agentId) => {
     const model = resolveDefaultModelForAgent({ cfg, agentId });
-    return (
-      resolveEffectiveAgentRuntime({
-        cfg,
-        provider: model.provider,
-        modelId: model.model,
-        agentId,
-      }) !== OPENCLAW_AGENT_RUNTIME_ID
-    );
+    const runtime = resolveEffectiveAgentRuntime({
+      cfg,
+      provider: model.provider,
+      modelId: model.model,
+      agentId,
+    });
+    if (runtime === OPENCLAW_AGENT_RUNTIME_ID) {
+      return false;
+    }
+    const harness = registry?.agentHarnesses.find((entry) => entry.harness.id === runtime)?.harness;
+    // Config-only doctor must not activate plugins or mistake unknown runtime capability for denial.
+    return harness !== undefined && harness.cloudPlacement?.devicePlacement === undefined;
   });
 }
 
@@ -88,16 +94,16 @@ export function collectNodeHostingPreconditionFindings(
         "Set plugins.entries.device-pair.enabled: true, ensure device-pair is not denied or excluded by plugins.allow, then restart the Gateway.",
     });
   }
-  if (lacksEmbeddedRuntimeRoute(cfg)) {
+  if (lacksDeviceCapableRuntimeRoute(cfg)) {
     findings.push({
       checkId: CHECK_ID,
       severity: "warning",
       message:
-        "No configured agent/model route resolves to the embedded runtime; paired-device dispatch will fail at launch because device runners cannot run Codex, ACPX, or another external harness.",
+        "No configured agent/model route resolves to a runtime that supports paired-device placement.",
       path: "agents",
       requirement: "device-session-runtime",
       fixHint:
-        'Set agentRuntime.id: "openclaw" on at least one provider/model route (models.providers.<provider>.agentRuntime, agents.defaults.models["provider/model"].agentRuntime, or agents.entries.<id>.models["provider/model"].agentRuntime), then select that agent/model for paired-device sessions. Runtime policy is model/provider-scoped; whole-agent runtime keys are ignored. For a multi-agent roster, set agents.ownership: "explicit".',
+        'Select an agent/model route whose runtime supports paired-device placement, then ensure its plugin is enabled and its required node commands are explicitly allowed. Runtime policy is model/provider-scoped; whole-agent runtime keys are ignored. For a multi-agent roster, set agents.ownership: "explicit".',
     });
   }
   if (usesIdentityHeadersWithoutMachineCredentials(cfg)) {
diff --git a/src/gateway/node-invoke-plugin-policy.test.ts b/src/gateway/node-invoke-plugin-policy.test.ts
index da7ee4b05a04..e874b8d30104 100644
--- a/src/gateway/node-invoke-plugin-policy.test.ts
+++ b/src/gateway/node-invoke-plugin-policy.test.ts
@@ -136,9 +136,9 @@ function createApprovalClientLookup(clients: GatewayClient[]): ApprovalClientLoo
     );
 }
 
-function createOperatorClient(): GatewayClient {
+function createOperatorClient(connId = "conn-requester"): GatewayClient {
   return createApprovalClient({
-    connId: "conn-requester",
+    connId,
     clientId: "client-owner",
     deviceId: "device-owner",
   });
@@ -168,6 +168,7 @@ function createApprovalRequestPolicy(params?: {
   description?: string;
   toolName?: string;
   agentId?: string;
+  allowedDecisions?: readonly ("allow-once" | "allow-always" | "deny")[];
 }): NodeInvokePolicyRegistration {
   return createDemoPolicy(async (ctx: OpenClawPluginNodeInvokePolicyContext) => {
     const approval = await ctx.approvals?.request({
@@ -175,6 +176,9 @@ function createApprovalRequestPolicy(params?: {
       description: params?.description ?? "Needs approval",
       ...(params?.toolName === undefined ? {} : { toolName: params.toolName }),
       ...(params?.agentId === undefined ? {} : { agentId: params.agentId }),
+      ...(params?.allowedDecisions === undefined
+        ? {}
+        : { allowedDecisions: params.allowedDecisions }),
       ...(params?.timeoutMs === undefined ? {} : { timeoutMs: params.timeoutMs }),
     });
     return { ok: true, payload: approval ?? null };
@@ -289,12 +293,11 @@ describe("applyPluginNodeInvokePolicy", () => {
     });
   });
 
-  it("streams approved dangerous commands through the existing scoped policy transport", async () => {
+  it("preserves session identity through approved dangerous streaming transport", async () => {
     const manager = new ExecApprovalManager<PluginApprovalRequestPayload>();
     const nodeSession = createNodeSession();
     nodeSession.pairingGeneration = "paired-generation-1";
-    const reviewer = createOperatorClient();
-    reviewer.connId = "conn-owner-approval";
+    const reviewer = createOperatorClient("conn-owner-approval");
     setDangerousDemoCommandRegistry([
       createDemoPolicy(async (policyContext) => {
         expect(policyContext.client?.scopes).toEqual(["operator.approvals"]);
@@ -338,6 +341,7 @@ describe("applyPluginNodeInvokePolicy", () => {
       nodeSession,
       command: DEMO_COMMAND,
       params: DEMO_PARAMS,
+      sessionKey: "agent:main:paired",
       nodeInvokeStream: stream,
     });
 
@@ -352,6 +356,7 @@ describe("applyPluginNodeInvokePolicy", () => {
       expect.objectContaining({
         expectedConnId: "conn-1",
         expectedPairingGeneration: "paired-generation-1",
+        sessionKey: "agent:main:paired",
         idleTimeoutMs: 5_000,
       }),
     );
@@ -733,11 +738,7 @@ describe("applyPluginNodeInvokePolicy", () => {
     const manager = new ExecApprovalManager<PluginApprovalRequestPayload>();
     const visibleConnIds = new Set(["conn-owner-approval"]);
     const getApprovalClientConnIds = createApprovalClientLookup([
-      createApprovalClient({
-        connId: "conn-owner-approval",
-        clientId: "client-owner",
-        deviceId: "device-owner",
-      }),
+      createOperatorClient("conn-owner-approval"),
       createApprovalClient({
         connId: "conn-other-approval",
         clientId: "client-other",
@@ -769,11 +770,7 @@ describe("applyPluginNodeInvokePolicy", () => {
   it("sanitizes node-policy approval titles at creation like the RPC ingress", async () => {
     const manager = new ExecApprovalManager<PluginApprovalRequestPayload>();
     const getApprovalClientConnIds = createApprovalClientLookup([
-      createApprovalClient({
-        connId: "conn-owner-approval",
-        clientId: "client-owner",
-        deviceId: "device-owner",
-      }),
+      createOperatorClient("conn-owner-approval"),
     ]);
     setDangerousDemoCommandRegistry([
       // Bidi override + zero-width space: reviewer-spoofing characters.
@@ -797,6 +794,29 @@ describe("applyPluginNodeInvokePolicy", () => {
     await expectApprovalResolution(resultPromise, manager, record);
   });
 
+  it("limits explicitly one-shot node-policy approvals to allow-once or deny", async () => {
+    const manager = new ExecApprovalManager<PluginApprovalRequestPayload>({
+      resolveAllowedDecisions: resolveCanonicalPluginApprovalRequestAllowedDecisions,
+    });
+    setDangerousDemoCommandRegistry([
+      createApprovalRequestPolicy({ allowedDecisions: ["allow-once"] }),
+    ]);
+    const { context } = createContext({
+      pluginApprovalManager: manager,
+      getApprovalClientConnIds: createApprovalClientLookup([
+        createOperatorClient("conn-owner-approval"),
+      ]),
+    });
+    const resultPromise = invokeDemoPolicy(context, createOperatorClient());
+
+    const record = await expectSinglePendingApproval(manager);
+    expect(record.request.allowedDecisions).toEqual(["allow-once", "deny"]);
+    expect(manager.resolve(record.id, "allow-always")).toBe(false);
+    expect(manager.listPendingRecords()).toHaveLength(1);
+
+    await expectApprovalResolution(resultPromise, manager, record);
+  });
+
   it("forwards plugin policy approvals to the originating turn source", async () => {
     const manager = new ExecApprovalManager<PluginApprovalRequestPayload>({
       validateAgentRuntimeDelegatedAuthority: () => true,
@@ -983,11 +1003,7 @@ describe("applyPluginNodeInvokePolicy", () => {
     const { context } = createContext({
       pluginApprovalManager: manager,
       getApprovalClientConnIds: createApprovalClientLookup([
-        createApprovalClient({
-          connId: "conn-owner-approval",
-          clientId: "client-owner",
-          deviceId: "device-owner",
-        }),
+        createOperatorClient("conn-owner-approval"),
       ]),
     });
     const resultPromise = invokeDemoPolicy(context, createOperatorClient());
@@ -1005,11 +1021,7 @@ describe("applyPluginNodeInvokePolicy", () => {
     const { context } = createContext({
       pluginApprovalManager: manager,
       getApprovalClientConnIds: createApprovalClientLookup([
-        createApprovalClient({
-          connId: "conn-owner-approval",
-          clientId: "client-owner",
-          deviceId: "device-owner",
-        }),
+        createOperatorClient("conn-owner-approval"),
       ]),
     });
     const resultPromise = invokeDemoPolicy(context, createOperatorClient());
@@ -1038,11 +1050,7 @@ describe("applyPluginNodeInvokePolicy", () => {
     const { context, invoke } = createContext({
       pluginApprovalManager: manager,
       getApprovalClientConnIds: createApprovalClientLookup([
-        createApprovalClient({
-          connId: "conn-owner-approval",
-          clientId: "client-owner",
-          deviceId: "device-owner",
-        }),
+        createOperatorClient("conn-owner-approval"),
       ]),
     });
 
@@ -1082,11 +1090,7 @@ describe("applyPluginNodeInvokePolicy", () => {
     const { context } = createContext({
       pluginApprovalManager: manager,
       getApprovalClientConnIds: createApprovalClientLookup([
-        createApprovalClient({
-          connId: "conn-owner-approval",
-          clientId: "client-owner",
-          deviceId: "device-owner",
-        }),
+        createOperatorClient("conn-owner-approval"),
       ]),
     });
     const resultPromise = invokeDemoPolicy(context, createOperatorClient());
diff --git a/src/gateway/node-invoke-plugin-policy.ts b/src/gateway/node-invoke-plugin-policy.ts
index 125bcae1abc8..affdefc3df92 100644
--- a/src/gateway/node-invoke-plugin-policy.ts
+++ b/src/gateway/node-invoke-plugin-policy.ts
@@ -7,6 +7,7 @@ import {
   sanitizeExecApprovalDisplayText,
   sanitizeExecApprovalWarningText,
 } from "../infra/exec-approval-command-display.js";
+import { resolveCanonicalPluginApprovalRequestAllowedDecisions } from "../infra/plugin-approval-canonical-decisions.js";
 import type { PluginApprovalRequestPayload } from "../infra/plugin-approvals.js";
 import { resolvePluginApprovalTimeoutMs } from "../infra/plugin-approvals.js";
 import type { PluginRegistry } from "../plugins/registry-types.js";
@@ -144,6 +145,13 @@ function createApprovalRuntime(params: {
           256,
         ),
         severity: input.severity ?? "warning",
+        ...(input.allowedDecisions === undefined
+          ? {}
+          : {
+              allowedDecisions: resolveCanonicalPluginApprovalRequestAllowedDecisions({
+                allowedDecisions: input.allowedDecisions,
+              }),
+            }),
         // toolName/agentId are interpolated into channel approval text; only
         // host-minted runtime identity values skip the display escape.
         toolName: sanitizeOptionalMeta(input.toolName),
@@ -232,6 +240,7 @@ export async function applyPluginNodeInvokePolicy(params: {
   nodeSession: NodeSession;
   command: string;
   params: unknown;
+  sessionKey?: string;
   turnSource?: {
     channel?: unknown;
     to?: unknown;
@@ -395,6 +404,7 @@ export async function applyPluginNodeInvokePolicy(params: {
       params: override.params ?? params.params,
       timeoutMs,
       ...(params.signal ? { signal: params.signal } : {}),
+      ...(params.sessionKey ? { sessionKey: params.sessionKey } : {}),
       idempotencyKey: override.idempotencyKey ?? params.idempotencyKey,
       ...(params.nodeInvokeStream && {
         onProgress: params.nodeInvokeStream.onProgress,
diff --git a/src/gateway/server-methods/environments.node-command-authority.test.ts b/src/gateway/server-methods/environments.node-command-authority.test.ts
new file mode 100644
index 000000000000..a0e5e93d9c42
--- /dev/null
+++ b/src/gateway/server-methods/environments.node-command-authority.test.ts
@@ -0,0 +1,112 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { listNodePairing } from "../../infra/device-pairing-node.js";
+import { listDevicePairing } from "../../infra/device-pairing.js";
+import { environmentsHandlers } from "./environments.js";
+
+vi.mock("../../infra/device-pairing.js", () => ({
+  listDevicePairing: vi.fn(),
+  resolveNodePairingState: vi.fn(),
+}));
+
+vi.mock("../../infra/device-pairing-node.js", () => ({
+  listNodePairing: vi.fn(),
+}));
+
+vi.mock("../node-registry-private.js", () => ({
+  collectNodeRunnerIssuesByNodeId: vi.fn(() => new Map()),
+  collectNodeWorkerBundleStatusByNodeId: vi.fn(() => new Map()),
+  collectNodeWorkerCapacityByNodeId: vi.fn(() => new Map()),
+  isNodeRunnerSessionHost: vi.fn(() => false),
+}));
+
+beforeEach(() => {
+  vi.mocked(listDevicePairing).mockResolvedValue({ paired: [] } as never);
+  vi.mocked(listNodePairing).mockResolvedValue({ paired: [] } as never);
+});
+
+describe("node environment command authority", () => {
+  it.each([
+    {
+      name: "projects sorted approved commands while preserving denied declarations",
+      declared: ["system.which", "codex.exec-server.stdio.v1", "system.run", "system.run"],
+      allow: ["codex.exec-server.stdio.v1"],
+      deny: ["system.run"],
+      expected: ["codex.exec-server.stdio.v1", "system.which"],
+    },
+    {
+      name: "withholds declared commands without explicit Gateway approval",
+      declared: ["codex.exec-server.stdio.v1"],
+      allow: [],
+      deny: [],
+      expected: [],
+    },
+    {
+      name: "honors Gateway denial even when the command was explicitly allowed",
+      declared: ["codex.exec-server.stdio.v1"],
+      allow: ["codex.exec-server.stdio.v1"],
+      deny: ["codex.exec-server.stdio.v1"],
+      expected: [],
+    },
+    {
+      name: "does not project approved commands the node did not declare",
+      declared: ["system.which"],
+      allow: ["codex.exec-server.stdio.v1"],
+      deny: [],
+      expected: ["system.which"],
+    },
+  ])("$name", async ({ declared, allow, deny, expected }) => {
+    const context = {
+      logGateway: { warn: vi.fn() },
+      getRuntimeConfig: () => ({ gateway: { nodes: { commands: { allow, deny } } } }),
+      nodeRegistry: {
+        listConnectedForPairingStates: () => [
+          {
+            nodeId: "node-exec",
+            connId: "conn-exec",
+            displayName: "Execution Node",
+            platform: "linux",
+            deviceFamily: "Linux",
+            caps: ["session.host"],
+            commands: declared,
+            connectedAtMs: 123,
+          },
+        ],
+      },
+    };
+
+    const listRespond = vi.fn();
+    await environmentsHandlers["environments.list"]?.({
+      params: {},
+      respond: listRespond,
+      context,
+    } as never);
+    const listPayload = listRespond.mock.calls.at(0)?.[1] as
+      | {
+          environments: Array<{
+            id: string;
+            capabilities?: string[];
+            invocableCommands?: string[];
+          }>;
+        }
+      | undefined;
+    const listed = listPayload?.environments.find(
+      (environment) => environment.id === "node:node-exec",
+    );
+
+    expect(listed?.invocableCommands ?? []).toEqual(expected);
+    for (const command of declared) {
+      expect(listed?.capabilities).toContain(command);
+    }
+
+    const statusRespond = vi.fn();
+    await environmentsHandlers["environments.status"]?.({
+      params: { environmentId: "node:node-exec" },
+      respond: statusRespond,
+      context,
+    } as never);
+    const statusPayload = statusRespond.mock.calls.at(0)?.[1] as
+      | { invocableCommands?: string[] }
+      | undefined;
+    expect(statusPayload?.invocableCommands ?? []).toEqual(expected);
+  });
+});
diff --git a/src/gateway/server-methods/environments.ts b/src/gateway/server-methods/environments.ts
index 56cab3ae553b..aee422119771 100644
--- a/src/gateway/server-methods/environments.ts
+++ b/src/gateway/server-methods/environments.ts
@@ -74,18 +74,25 @@ function summarizeNodeEnvironment(
   // runtimes still advertise useful execution surfaces in one stable list.
   const capabilities = uniqueSortedStrings(node.caps, node.commands);
   const platform = node.platform?.trim();
-  const desktop =
-    node.connected === true &&
-    isNodeCommandAllowed({
-      command: NODE_DESKTOP_STREAM_COMMAND,
-      declaredCommands: node.commands,
-      allowlist: resolveNodeCommandAllowlist(config, {
-        platform: node.platform,
-        deviceFamily: node.deviceFamily,
-        commands: node.commands,
-        approvedCommands: node.commands,
-      }),
-    }).ok;
+  const allowlist =
+    node.connected === true
+      ? resolveNodeCommandAllowlist(config, {
+          platform: node.platform,
+          deviceFamily: node.deviceFamily,
+          commands: node.commands,
+          approvedCommands: node.commands,
+        })
+      : undefined;
+  const invocableCommands = allowlist
+    ? uniqueSortedStrings(node.commands)
+        .filter(
+          (command) =>
+            command.length <= 128 &&
+            isNodeCommandAllowed({ command, declaredCommands: node.commands, allowlist }).ok,
+        )
+        .slice(0, 128)
+    : [];
+  const desktop = invocableCommands.includes(NODE_DESKTOP_STREAM_COMMAND);
   return {
     id: `node:${node.nodeId}`,
     type: "node",
@@ -104,6 +111,7 @@ function summarizeNodeEnvironment(
     trust: "persistent",
     ...(desktop ? { desktop: true } : {}),
     ...(capabilities.length > 0 ? { capabilities } : {}),
+    ...(invocableCommands.length > 0 ? { invocableCommands } : {}),
     ...(node.issues?.length ? { issues: [...node.issues] } : {}),
   };
 }
diff --git a/src/gateway/server-methods/models-list-result.openai-routes.test.ts b/src/gateway/server-methods/models-list-result.openai-routes.test.ts
index 14e5ff585bb8..755c53f40730 100644
--- a/src/gateway/server-methods/models-list-result.openai-routes.test.ts
+++ b/src/gateway/server-methods/models-list-result.openai-routes.test.ts
@@ -24,17 +24,17 @@ const IMPLICIT_OPENCLAW_RUNTIME = {
   id: "openclaw",
   cloudPlacementSupported: true,
   cloudPlacementExecutionMode: "worker-turn",
+  devicePlacement: { requiredNodeCommands: [], consumesWorkerSlot: true },
   devicePlacementSupported: true,
   source: "implicit",
 } as const;
 const MODEL_CODEX_RUNTIME = { ...IMPLICIT_CODEX_RUNTIME, source: "model" } as const;
 
-function preparedOwnerFacts(config: OpenClawConfig) {
-  return {
+const preparedOwnerFacts = (config: OpenClawConfig) =>
+  ({
     authStore: { version: 1, profiles: {} },
     metadataSnapshot: loadManifestMetadataSnapshot({ config, env: process.env }),
-  } as const;
-}
+  }) as const;
 
 function emptyPreparedOwner(config: OpenClawConfig) {
   return {
diff --git a/src/gateway/server-methods/models.test.ts b/src/gateway/server-methods/models.test.ts
index 80b4359fcb6c..54a5ae0baee9 100644
--- a/src/gateway/server-methods/models.test.ts
+++ b/src/gateway/server-methods/models.test.ts
@@ -17,6 +17,7 @@ import { clearRuntimeConfigSnapshot, setRuntimeConfigSnapshot } from "../../conf
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { loadManifestMetadataSnapshot } from "../../plugins/manifest-contract-eligibility.js";
 import type { PluginMetadataSnapshot } from "../../plugins/plugin-metadata-snapshot.types.js";
+import type { GatewayAgentRuntime } from "../../shared/session-types.js";
 import { withEnvAsync } from "../../test-utils/env.js";
 import {
   createOpenClawTestState,
@@ -30,6 +31,11 @@ import {
 import { modelsHandlers } from "./models.js";
 import type { RespondFn } from "./types.js";
 
+const OPENCLAW_DEVICE_PLACEMENT: NonNullable<GatewayAgentRuntime["devicePlacement"]> = {
+  requiredNodeCommands: [],
+  consumesWorkerSlot: true,
+};
+
 const modelPluginMetadataSnapshot = vi.hoisted(() => {
   const plugins = [
     {
@@ -995,6 +1001,7 @@ describe("models.list", () => {
                   id: "openclaw",
                   cloudPlacementSupported: true,
                   cloudPlacementExecutionMode: "worker-turn",
+                  devicePlacement: OPENCLAW_DEVICE_PLACEMENT,
                   devicePlacementSupported: true,
                   source: "implicit",
                 },
@@ -1056,6 +1063,7 @@ describe("models.list", () => {
                   id: "openclaw",
                   cloudPlacementSupported: true,
                   cloudPlacementExecutionMode: "worker-turn",
+                  devicePlacement: OPENCLAW_DEVICE_PLACEMENT,
                   devicePlacementSupported: true,
                   source: "implicit",
                 },
@@ -1108,6 +1116,7 @@ describe("models.list", () => {
                 id: "openclaw",
                 cloudPlacementSupported: true,
                 cloudPlacementExecutionMode: "worker-turn",
+                devicePlacement: OPENCLAW_DEVICE_PLACEMENT,
                 devicePlacementSupported: true,
                 source: "implicit",
               },
diff --git a/src/gateway/server-methods/nodes.invoke.ts b/src/gateway/server-methods/nodes.invoke.ts
index a5d9e999df73..574218cf525e 100644
--- a/src/gateway/server-methods/nodes.invoke.ts
+++ b/src/gateway/server-methods/nodes.invoke.ts
@@ -440,6 +440,7 @@ export const nodeInvokeHandlers: GatewayRequestHandlers = {
               nodeSession,
               command,
               params: forwardedParams.params,
+              ...(sessionKey ? { sessionKey } : {}),
               turnSource: {
                 channel: p.turnSourceChannel,
                 to: p.turnSourceTo,
diff --git a/src/gateway/server-methods/sessions-dispatch.test-support.ts b/src/gateway/server-methods/sessions-dispatch.test-support.ts
index dd609050dbf9..951ca118f4ad 100644
--- a/src/gateway/server-methods/sessions-dispatch.test-support.ts
+++ b/src/gateway/server-methods/sessions-dispatch.test-support.ts
@@ -1,6 +1,13 @@
 import { expectDefined } from "@openclaw/normalization-core";
 import { vi } from "vitest";
+import {
+  GATEWAY_CLIENT_IDS,
+  GATEWAY_CLIENT_MODES,
+} from "../../../packages/gateway-protocol/src/client-info.js";
 import type { SessionEntry } from "../../config/sessions/types.js";
+import { NODE_WORKER_SUPERVISOR_PROTOCOL_FEATURE } from "../../infra/node-runner-inventory.js";
+import type { NodeWorkerSupervisorNodeProof } from "../node-registry-private.js";
+import { bindDeviceWorkerAvailability } from "../worker-environments/device-provider.js";
 import type { WorkerSessionPlacementRecord } from "../worker-environments/placement-store.js";
 import type { GatewayRequestContext, RespondFn, SessionMutationAuthorization } from "./types.js";
 
@@ -119,6 +126,26 @@ export function makeSessionTarget(entry?: DispatchSessionEntry) {
 export function makeDispatchTestContext(
   overrides: Partial<GatewayRequestContext> = {},
 ): GatewayRequestContext {
+  const workerEnvironmentService = overrides.workerEnvironmentService ?? {
+    supportsExecutionMode: () => true,
+  };
+  if (!overrides.workerEnvironmentService) {
+    bindDeviceWorkerAvailability(workerEnvironmentService, async (deviceId) => {
+      const observed = overrides.nodeRegistry?.get?.(deviceId);
+      const node: NodeWorkerSupervisorNodeProof = {
+        nodeId: deviceId,
+        connId: observed?.connId ?? `conn-${deviceId}`,
+        pairingIdentity: observed?.pairingIdentity ?? `identity-${deviceId}`,
+        pairingGeneration: observed?.pairingGeneration ?? `generation-${deviceId}`,
+        clientId: GATEWAY_CLIENT_IDS.NODE_HOST,
+        clientMode: GATEWAY_CLIENT_MODES.NODE,
+        protocolFeature: NODE_WORKER_SUPERVISOR_PROTOCOL_FEATURE,
+        workerHost: { enabled: true, capacity: { total: 2, available: 2 } },
+        commands: observed?.commands ?? ["system.run", "codex.exec-server.stdio.v1"],
+      };
+      return { available: true, node };
+    });
+  }
   return {
     getRuntimeConfig: () => ({
       cloudWorkers: {
@@ -128,10 +155,7 @@ export function makeDispatchTestContext(
       },
     }),
     ...overrides,
-    workerEnvironmentService: {
-      supportsExecutionMode: () => true,
-      ...overrides.workerEnvironmentService,
-    } as never,
+    workerEnvironmentService: workerEnvironmentService as never,
   } as unknown as GatewayRequestContext;
 }
 
diff --git a/src/gateway/server-methods/sessions-dispatch.ts b/src/gateway/server-methods/sessions-dispatch.ts
index 37c85de264bd..6ea009c766bc 100644
--- a/src/gateway/server-methods/sessions-dispatch.ts
+++ b/src/gateway/server-methods/sessions-dispatch.ts
@@ -14,11 +14,12 @@ import { formatErrorMessage } from "../../infra/errors.js";
 import { runCommandWithTimeout } from "../../process/exec.js";
 import { resolveRequestedSessionAgentId as resolveRequestedGlobalAgentId } from "../session-request-agent.js";
 import { SessionMutationAuthorizationChangedError } from "../session-sharing.js";
+import { resolveDevicePlacementEligibility } from "../worker-environments/device-placement-eligibility.js";
 import { resolveWorkerPlacementDestination } from "../worker-environments/placement-destination.js";
 import { projectWorkerSessionPlacement } from "../worker-environments/placement-projector.js";
 import type { WorkerSessionPlacementRecord } from "../worker-environments/placement-record.js";
 import {
-  resolveWorkerPlacementExecutionMode,
+  resolveWorkerPlacementCapabilities,
   resolveWorkerPlacementSessionRuntime,
 } from "../worker-environments/placement-session-runtime.js";
 import { isFailedWorkerPlacementEnvironmentGone } from "../worker-environments/session-placement-lifecycle.js";
@@ -136,28 +137,41 @@ async function resolveProjectProfileDestination(params: {
   return { profileId };
 }
 
-function validateDispatchExecutionMode(params: {
+async function validateDispatchExecutionMode(params: {
   context: GatewayRequestContext;
   executionMode: "worker-turn" | "remote-exec";
   sessionRuntime: string;
+  devicePlacement: ReturnType<typeof resolveWorkerPlacementCapabilities>["devicePlacement"];
   target: { profileId: string; deviceId?: string };
   respond: RespondFn;
-}): boolean {
+}): Promise<boolean> {
+  if (params.target.deviceId !== undefined) {
+    const eligibility = await resolveDevicePlacementEligibility({
+      environmentService: params.context.workerEnvironmentService,
+      deviceId: params.target.deviceId,
+      runtimeId: params.sessionRuntime,
+      requirement: params.devicePlacement,
+      config: params.context.getRuntimeConfig(),
+      currentNode: params.context.nodeRegistry?.get?.(params.target.deviceId),
+    });
+    if (eligibility.ok) {
+      return true;
+    }
+    respondInvalidWorkerSession(params.respond, eligibility.error);
+    return false;
+  }
   if (
     params.executionMode !== "remote-exec" ||
-    (params.target.deviceId === undefined &&
-      params.context.workerEnvironmentService?.supportsExecutionMode?.(
-        params.target.profileId,
-        params.executionMode,
-      ) === true)
+    params.context.workerEnvironmentService?.supportsExecutionMode?.(
+      params.target.profileId,
+      params.executionMode,
+    ) === true
   ) {
     return true;
   }
   respondInvalidWorkerSession(
     params.respond,
-    params.target.deviceId !== undefined
-      ? `runtime ${params.sessionRuntime} cannot dispatch to a paired device; select an agent/model route with agentRuntime.id "openclaw" (the embedded runtime), or choose an SSH-backed cloud worker provider`
-      : `runtime ${params.sessionRuntime} requires an SSH-backed cloud worker provider; choose a provider that supports remote-exec, or select an agent/model route with agentRuntime.id "openclaw"`,
+    `runtime ${params.sessionRuntime} requires an SSH-backed cloud worker provider; choose a provider that supports remote-exec, or select an agent/model route with agentRuntime.id "openclaw"`,
   );
   return false;
 }
@@ -259,7 +273,7 @@ export const sessionDispatchHandlers: GatewayRequestHandlers = {
       agentId: target.target.agentId,
       sessionKey: target.canonicalKey,
     });
-    const executionMode = resolveWorkerPlacementExecutionMode(sessionRuntime);
+    const { executionMode, devicePlacement } = resolveWorkerPlacementCapabilities(sessionRuntime);
     if (!executionMode) {
       respondInvalidWorkerSession(
         respond,
@@ -269,13 +283,14 @@ export const sessionDispatchHandlers: GatewayRequestHandlers = {
     }
     if (
       dispatchTarget &&
-      !validateDispatchExecutionMode({
+      !(await validateDispatchExecutionMode({
         context,
         executionMode,
         sessionRuntime,
+        devicePlacement,
         target: dispatchTarget,
         respond,
-      })
+      }))
     ) {
       return;
     }
@@ -328,13 +343,14 @@ export const sessionDispatchHandlers: GatewayRequestHandlers = {
     }
     if (
       canUseProjectProfile &&
-      !validateDispatchExecutionMode({
+      !(await validateDispatchExecutionMode({
         context,
         executionMode,
         sessionRuntime,
+        devicePlacement,
         target: dispatchTarget,
         respond,
-      })
+      }))
     ) {
       return;
     }
@@ -346,6 +362,7 @@ export const sessionDispatchHandlers: GatewayRequestHandlers = {
           agentId: target.target.agentId,
           executionMode,
           ...dispatchTarget,
+          ...(dispatchTarget.deviceId && devicePlacement ? { devicePlacement } : {}),
         },
         () =>
           emitSessionsChanged(context, {
diff --git a/src/gateway/server-methods/sessions.dispatch.device.test.ts b/src/gateway/server-methods/sessions.dispatch.device.test.ts
index bfc4d04b4a85..9c5b0ca1f205 100644
--- a/src/gateway/server-methods/sessions.dispatch.device.test.ts
+++ b/src/gateway/server-methods/sessions.dispatch.device.test.ts
@@ -1,14 +1,21 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   GATEWAY_CLIENT_IDS,
   GATEWAY_CLIENT_MODES,
 } from "../../../packages/gateway-protocol/src/client-info.js";
 import { ErrorCodes } from "../../../packages/gateway-protocol/src/index.js";
+import { registerAgentHarness } from "../../agents/harness/registry.js";
 import type { PairedDevice } from "../../infra/device-pairing.types.js";
 import { NODE_WORKER_SUPERVISOR_PROTOCOL_FEATURE } from "../../infra/node-runner-inventory.js";
+import { createEmptyPluginRegistry } from "../../plugins/registry-empty.js";
+import {
+  getActivePluginRegistry,
+  resetPluginRuntimeStateForTest,
+  setActivePluginRegistry,
+} from "../../plugins/runtime.js";
 import {
   closeOpenClawStateDatabaseForTest,
   openOpenClawStateDatabase,
@@ -32,6 +39,21 @@ import {
 
 const dispatchTestMocks = getDispatchTestMocks();
 
+function useDeviceSession(agentRuntimeOverride?: string): void {
+  dispatchTestMocks.resolveTarget.mockReturnValue(
+    makeSessionTarget({
+      sessionId: dispatchTestSessionId,
+      ...(agentRuntimeOverride ? { agentRuntimeOverride } : {}),
+      worktree: { id: "worktree-1", branch: "openclaw/device-test", repoRoot: "/repo" },
+    }),
+  );
+  dispatchTestMocks.findLiveByOwner.mockReturnValue({
+    id: "worktree-1",
+    ownerKind: "session",
+    ownerId: dispatchTestSessionKey,
+  });
+}
+
 function pairedNode(deviceId: string): PairedDevice {
   return {
     deviceId,
@@ -72,17 +94,7 @@ describe("sessions.dispatch device targets", () => {
   });
 
   it("synthesizes the core device-provider target for a connected session-capable node", async () => {
-    dispatchTestMocks.resolveTarget.mockReturnValue(
-      makeSessionTarget({
-        sessionId: dispatchTestSessionId,
-        worktree: { id: "worktree-1", branch: "openclaw/device-test", repoRoot: "/repo" },
-      }),
-    );
-    dispatchTestMocks.findLiveByOwner.mockReturnValue({
-      id: "worktree-1",
-      ownerKind: "session",
-      ownerId: dispatchTestSessionKey,
-    });
+    useDeviceSession();
     const dispatch = vi.fn().mockResolvedValue({
       sessionId: dispatchTestSessionId,
       agentId: "main",
@@ -136,17 +148,7 @@ describe("sessions.dispatch device targets", () => {
   });
 
   it("returns a device dispatch failure to the operator", async () => {
-    dispatchTestMocks.resolveTarget.mockReturnValue(
-      makeSessionTarget({
-        sessionId: dispatchTestSessionId,
-        worktree: { id: "worktree-1", branch: "openclaw/device-test", repoRoot: "/repo" },
-      }),
-    );
-    dispatchTestMocks.findLiveByOwner.mockReturnValue({
-      id: "worktree-1",
-      ownerKind: "session",
-      ownerId: dispatchTestSessionKey,
-    });
+    useDeviceSession();
     const dispatch = vi
       .fn()
       .mockRejectedValue(
@@ -171,6 +173,144 @@ describe("sessions.dispatch device targets", () => {
     );
   });
 
+  describe("runtime-owned paired-node command authority", () => {
+    let previousPluginRegistry: ReturnType<typeof getActivePluginRegistry>;
+
+    beforeEach(() => {
+      previousPluginRegistry = getActivePluginRegistry();
+      setActivePluginRegistry(
+        createEmptyPluginRegistry(),
+        "sessions-dispatch-device-test",
+        "default",
+      );
+      registerAgentHarness({
+        id: "codex",
+        label: "Codex",
+        autoSelection: { providerIds: ["codex", "openai"] },
+        cloudPlacement: {
+          mode: "remote-exec",
+          devicePlacement: {
+            requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+            consumesWorkerSlot: false,
+          },
+        },
+        supports: () => ({ supported: true, priority: 10 }),
+        async runAttempt() {
+          throw new Error("not used");
+        },
+      });
+    });
+
+    afterEach(() => {
+      if (previousPluginRegistry) {
+        setActivePluginRegistry(
+          previousPluginRegistry,
+          "sessions-dispatch-device-test-restore",
+          "default",
+        );
+      } else {
+        resetPluginRuntimeStateForTest();
+      }
+    });
+
+    it.each([
+      {
+        name: "missing",
+        declaredCommands: ["system.run"],
+        commandPolicy: { allow: ["codex.exec-server.stdio.v1"] },
+      },
+      {
+        name: "declared but denied",
+        declaredCommands: ["system.run", "codex.exec-server.stdio.v1"],
+        commandPolicy: { deny: ["codex.exec-server.stdio.v1"] },
+      },
+    ])("rejects a $name required paired-node command before dispatch", async (scenario) => {
+      useDeviceSession("codex");
+      const dispatch = vi.fn();
+      const respond = await invokeSessionDispatch(
+        makeDispatchTestContext({
+          getRuntimeConfig: () => ({
+            gateway: { nodes: { commands: scenario.commandPolicy } },
+          }),
+          nodeRegistry: {
+            get: () => ({
+              nodeId: "device-1",
+              platform: "darwin",
+              commands: scenario.declaredCommands,
+              client: {},
+            }),
+          } as never,
+          workerPlacementDispatchService: { dispatch },
+          workerSessionPlacementService: { getMany: () => new Map() },
+        }),
+        { deviceId: "device-1" },
+      );
+
+      expect(dispatch).not.toHaveBeenCalled();
+      expect(respond).toHaveBeenCalledWith(
+        false,
+        undefined,
+        expect.objectContaining({
+          code: ErrorCodes.INVALID_REQUEST,
+          message: expect.stringMatching(/command.*(enabled|approved|declared)/i),
+        }),
+      );
+    });
+
+    it.each([
+      { name: "dispatches an opted-in runtime", runtimeId: "codex", supported: true },
+      { name: "rejects a runtime without opt-in", runtimeId: "cloud-only", supported: false },
+    ])("$name to a paired device", async ({ runtimeId, supported }) => {
+      if (!supported) {
+        registerAgentHarness({
+          id: runtimeId,
+          label: "Cloud only",
+          cloudPlacement: { mode: "remote-exec" },
+          supports: () => ({ supported: true }),
+          runAttempt: async () => {
+            throw new Error("not used");
+          },
+        });
+      }
+      useDeviceSession(runtimeId);
+      const dispatch = vi.fn().mockRejectedValue(new Error("paired-device dispatch reached"));
+      const respond = await invokeSessionDispatch(
+        makeDispatchTestContext({
+          getRuntimeConfig: () => ({
+            gateway: { nodes: { commands: { allow: ["codex.exec-server.stdio.v1"] } } },
+          }),
+          workerPlacementDispatchService: { dispatch },
+          workerSessionPlacementService: { getMany: () => new Map() },
+        }),
+        { deviceId: "device-1" },
+      );
+
+      if (supported) {
+        expect(dispatch).toHaveBeenCalledWith(
+          expect.objectContaining({
+            executionMode: "remote-exec",
+            profileId: "device:device-1",
+            deviceId: "device-1",
+          }),
+          expect.any(Function),
+          undefined,
+        );
+      } else {
+        expect(dispatch).not.toHaveBeenCalled();
+      }
+      expect(respond).toHaveBeenCalledWith(
+        false,
+        undefined,
+        expect.objectContaining({
+          code: supported ? ErrorCodes.UNAVAILABLE : ErrorCodes.INVALID_REQUEST,
+          message: supported
+            ? "paired-device dispatch reached"
+            : "runtime cloud-only does not support paired-device placement; select a compatible runtime or cloud worker provider",
+        }),
+      );
+    });
+  });
+
   it.each([
     {
       name: "full",
@@ -185,7 +325,7 @@ describe("sessions.dispatch device targets", () => {
       rejectedMessage: "at capacity",
     },
   ])(
-    "carries a $name node rejection through the placement row and operator response",
+    "rejects a $name node before mutating placement or provisioning",
     async ({ nodes, expectedMessage, rejectedMessage }) => {
       const root = await fs.mkdtemp(
         path.join(await fs.realpath(os.tmpdir()), "openclaw-session-dispatch-device-"),
@@ -205,37 +345,25 @@ describe("sessions.dispatch device targets", () => {
         });
         bindDeviceWorkerAvailability(harness.environments, runtime.resolveAvailability);
 
-        dispatchTestMocks.resolveTarget.mockReturnValue(
-          makeSessionTarget({
-            sessionId: dispatchTestSessionId,
-            worktree: { id: "worktree-1", branch: "openclaw/device-test", repoRoot: "/repo" },
-          }),
-        );
-        dispatchTestMocks.findLiveByOwner.mockReturnValue({
-          id: "worktree-1",
-          ownerKind: "session",
-          ownerId: dispatchTestSessionKey,
-        });
+        useDeviceSession();
         const respond = await invokeSessionDispatch(
           makeDispatchTestContext({
             workerPlacementDispatchService: harness.service,
             workerSessionPlacementService: placements,
+            workerEnvironmentService: harness.environments as never,
           }),
           { deviceId: "device-1" },
         );
 
         const placement = placements.get(dispatchTestSessionId);
-        expect(placement).toMatchObject({
-          state: "failed",
-          recoveryError: expect.stringContaining(expectedMessage),
-          terminalReason: expect.stringContaining(expectedMessage),
-        });
-        expect(placement?.recoveryError).not.toContain(rejectedMessage);
+        expect(placement).toBeUndefined();
+        expect(harness.environments.createFromProfileSnapshot).not.toHaveBeenCalled();
+        expect(harness.environments.startTunnel).not.toHaveBeenCalled();
         expect(respond).toHaveBeenCalledWith(
           false,
           undefined,
           expect.objectContaining({
-            code: ErrorCodes.UNAVAILABLE,
+            code: ErrorCodes.INVALID_REQUEST,
             message: expect.stringContaining(expectedMessage),
           }),
         );
diff --git a/src/gateway/server-methods/sessions.dispatch.test.ts b/src/gateway/server-methods/sessions.dispatch.test.ts
index d5944eda31e7..55fd1a476929 100644
--- a/src/gateway/server-methods/sessions.dispatch.test.ts
+++ b/src/gateway/server-methods/sessions.dispatch.test.ts
@@ -39,11 +39,17 @@ function activePlacementRecord(): Extract<WorkerSessionPlacementRecord, { state:
 describe("sessions.dispatch", () => {
   beforeEach(() => {
     setActivePluginRegistry(createEmptyPluginRegistry(), "sessions-dispatch-test", "default");
-    const codexHarness: AgentHarness & { cloudPlacement: { mode: "remote-exec" } } = {
+    const codexHarness: AgentHarness = {
       id: "codex",
       label: "Codex",
       autoSelection: { providerIds: ["codex", "openai"] },
-      cloudPlacement: { mode: "remote-exec" },
+      cloudPlacement: {
+        mode: "remote-exec",
+        devicePlacement: {
+          requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+          consumesWorkerSlot: false,
+        },
+      },
       supports: () => ({ supported: true, priority: 10 }),
       async runAttempt() {
         throw new Error("not used");
@@ -436,35 +442,6 @@ describe("sessions.dispatch", () => {
     );
   });
 
-  it("explains how to make a codex session eligible for paired-device dispatch", async () => {
-    mocks.resolveTarget.mockReturnValue(
-      targetWithEntry({
-        sessionId,
-        agentRuntimeOverride: "codex",
-        worktree: { id: "worktree-1", branch: "openclaw/device-test", repoRoot: "/repo" },
-      }),
-    );
-    const dispatch = vi.fn();
-    const respond = await invoke(
-      makeContext({
-        workerPlacementDispatchService: { dispatch },
-        workerSessionPlacementService: { getMany: () => new Map() },
-      }),
-      { deviceId: "device-1" },
-    );
-
-    expect(dispatch).not.toHaveBeenCalled();
-    expect(respond).toHaveBeenCalledWith(
-      false,
-      undefined,
-      expect.objectContaining({
-        code: ErrorCodes.INVALID_REQUEST,
-        message:
-          'runtime codex cannot dispatch to a paired device; select an agent/model route with agentRuntime.id "openclaw" (the embedded runtime), or choose an SSH-backed cloud worker provider',
-      }),
-    );
-  });
-
   it("passes a per-dispatch machine class to placement", async () => {
     mocks.resolveTarget.mockReturnValue(
       targetWithEntry({
diff --git a/src/gateway/server-plugins-node-runtime.ts b/src/gateway/server-plugins-node-runtime.ts
index a4ae427d30a5..ee97b891db34 100644
--- a/src/gateway/server-plugins-node-runtime.ts
+++ b/src/gateway/server-plugins-node-runtime.ts
@@ -77,6 +77,7 @@ export async function openGatewayNodeDuplex(options: {
   const endpoint = createNodeDuplexEndpoint({
     requireReady: true,
     maxMessageBytes: params.maxMessageBytes,
+    maxOutstandingDeliveryBytes: params.maxOutstandingDeliveryBytes,
     sendFrame(frame) {
       assertRuntimeCurrent();
       if (!invokeId || !framedReady) {
diff --git a/src/gateway/server-worker-placement-move-destination.test.ts b/src/gateway/server-worker-placement-move-destination.test.ts
new file mode 100644
index 000000000000..901eda718d57
--- /dev/null
+++ b/src/gateway/server-worker-placement-move-destination.test.ts
@@ -0,0 +1,142 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  GATEWAY_CLIENT_IDS,
+  GATEWAY_CLIENT_MODES,
+} from "../../packages/gateway-protocol/src/client-info.js";
+import { NODE_WORKER_SUPERVISOR_PROTOCOL_FEATURE } from "../infra/node-runner-inventory.js";
+import { createGatewayWorkerPlacementMoveDestinationResolver } from "./server-worker-placement-move-destination.js";
+import { bindDeviceWorkerAvailability } from "./worker-environments/device-provider.js";
+import { createWorkerPlacementMoveService } from "./worker-environments/placement-move-service.js";
+
+const SESSION_KEY = "agent:main:move-source";
+const CODEX_COMMAND = "codex.exec-server.stdio.v1";
+const DEVICE_REQUIREMENT = { requiredNodeCommands: [CODEX_COMMAND], consumesWorkerSlot: false };
+
+describe("worker placement move destination owner", () => {
+  it.each([
+    {
+      name: "allows an explicitly enabled zero-slot paired-device runtime",
+      target: { kind: "device" as const, deviceId: "paired-build-mac" },
+      supported: true,
+      expectedError: "source placement barrier started",
+      barrierCalls: 1,
+    },
+    {
+      name: "rejects an unsupported paired-device runtime before source mutation",
+      target: { kind: "device" as const, deviceId: "paired-build-mac" },
+      supported: false,
+      expectedError: "runtime codex does not support paired-device placement",
+      barrierCalls: 0,
+    },
+    {
+      name: "rejects an incompatible profile before changing its exact active source",
+      target: { kind: "profile" as const, profileId: "incompatible" },
+      supported: false,
+      expectedError: "worker profile incompatible does not support remote-exec placement",
+      barrierCalls: 0,
+    },
+  ])("$name", async ({ target, supported, expectedError, barrierCalls }) => {
+    const source = Object.freeze({
+      sessionId: "session-move-source",
+      state: "active",
+      generation: 4,
+      environmentId: "environment-source",
+      activeOwnerEpoch: 2,
+      executionMode: "remote-exec",
+    });
+    const sourceBefore = JSON.stringify(source);
+    const entry = { sessionId: source.sessionId, worktree: { id: "worktree-recovery" } };
+    const config = {
+      cloudWorkers: { profiles: { incompatible: { provider: "worker-only" } } },
+      gateway: { nodes: { commands: { allow: [CODEX_COMMAND] } } },
+    };
+    const supportsExecutionMode = vi.fn(() => false);
+    const environments = { supportsExecutionMode };
+    bindDeviceWorkerAvailability(environments, async (deviceId) => ({
+      available: true,
+      node: {
+        nodeId: deviceId,
+        connId: `conn-${deviceId}`,
+        pairingIdentity: `identity-${deviceId}`,
+        pairingGeneration: `generation-${deviceId}`,
+        clientId: GATEWAY_CLIENT_IDS.NODE_HOST,
+        clientMode: GATEWAY_CLIENT_MODES.NODE,
+        protocolFeature: NODE_WORKER_SUPERVISOR_PROTOCOL_FEATURE,
+        workerHost: { enabled: true, capacity: { total: 2, available: 0 } },
+        commands: [CODEX_COMMAND],
+      },
+    }));
+    const resolveDestination = createGatewayWorkerPlacementMoveDestinationResolver({
+      environments: environments as never,
+      getConfig: () => config,
+      loadSessionRuntime: async () =>
+        ({
+          managedWorktrees: {
+            findLiveByOwner: () => ({
+              id: "worktree-recovery",
+              ownerId: SESSION_KEY,
+              path: "/gateway/workspace",
+            }),
+          },
+          resolveGatewaySessionStoreTargetWithStore: () => ({
+            agentId: "main",
+            canonicalKey: SESSION_KEY,
+            storePath: "/gateway/session.sqlite",
+            storeKeys: [SESSION_KEY],
+            store: { [SESSION_KEY]: entry },
+          }),
+          resolveCanonicalSessionEntryFromStoreKeys: () => entry,
+          resolveWorkerPlacementSessionRuntime: () => "codex",
+          resolveWorkerPlacementCapabilities: () => ({
+            executionMode: "remote-exec",
+            ...(supported ? { devicePlacement: DEVICE_REQUIREMENT } : {}),
+          }),
+        }) as never,
+    });
+    const runMoveBarrier = vi.fn(async () => {
+      throw new Error("source placement barrier started");
+    });
+    const reclaimSource = vi.fn();
+    const dispatch = vi.fn();
+    const beginPlacementMove = vi.fn();
+    const destroy = vi.fn();
+    const moves = createWorkerPlacementMoveService({
+      placements: {
+        get: () => source,
+        getPlacementMove: () => undefined,
+        beginPlacementMove,
+      } as never,
+      environments: { get: () => undefined, destroy } as never,
+      runMoveBarrier,
+      dispatch,
+      reclaimSource,
+      validateAbandonSource: vi.fn(),
+      abandonSource: vi.fn(),
+      resolveDestination,
+    });
+
+    await expect(
+      moves.move({
+        sessionId: source.sessionId,
+        sessionKey: SESSION_KEY,
+        agentId: "main",
+        source: {
+          generation: source.generation,
+          environmentId: source.environmentId,
+          ownerEpoch: source.activeOwnerEpoch,
+        },
+        target,
+      }),
+    ).rejects.toThrow(expectedError);
+
+    expect(runMoveBarrier).toHaveBeenCalledTimes(barrierCalls);
+    expect(beginPlacementMove).not.toHaveBeenCalled();
+    expect(reclaimSource).not.toHaveBeenCalled();
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(destroy).not.toHaveBeenCalled();
+    expect(JSON.stringify(source)).toBe(sourceBefore);
+    if (target.kind === "profile") {
+      expect(supportsExecutionMode).toHaveBeenCalledWith("incompatible", "remote-exec");
+    }
+  });
+});
diff --git a/src/gateway/server-worker-placement-move-destination.ts b/src/gateway/server-worker-placement-move-destination.ts
new file mode 100644
index 000000000000..5b8ccd0917a1
--- /dev/null
+++ b/src/gateway/server-worker-placement-move-destination.ts
@@ -0,0 +1,81 @@
+import type { managedWorktrees } from "../agents/worktrees/service.js";
+import type { OpenClawConfig } from "../config/types.openclaw.js";
+import { resolveWorkerPlacementSessionTarget } from "./server-worker-placement-session-target.js";
+import type * as sessionUtils from "./session-utils.js";
+import { resolveDevicePlacementEligibility } from "./worker-environments/device-placement-eligibility.js";
+import { resolveWorkerPlacementDestination } from "./worker-environments/placement-destination.js";
+import type * as placementSessionRuntime from "./worker-environments/placement-session-runtime.js";
+import type {
+  WorkerPlacementMoveDestination,
+  WorkerPlacementMoveRequest,
+} from "./worker-environments/service-contract.js";
+import type { WorkerEnvironmentService } from "./worker-environments/service.js";
+
+type MovePlacementSessionRuntime = {
+  managedWorktrees: typeof managedWorktrees;
+  resolveWorkerPlacementCapabilities: typeof placementSessionRuntime.resolveWorkerPlacementCapabilities;
+  resolveWorkerPlacementSessionRuntime: typeof placementSessionRuntime.resolveWorkerPlacementSessionRuntime;
+  resolveCanonicalSessionEntryFromStoreKeys: typeof sessionUtils.resolveCanonicalSessionEntryFromStoreKeys;
+  resolveGatewaySessionStoreTargetWithStore: typeof sessionUtils.resolveGatewaySessionStoreTargetWithStore;
+};
+
+export function createGatewayWorkerPlacementMoveDestinationResolver(params: {
+  environments: WorkerEnvironmentService;
+  getConfig: () => OpenClawConfig;
+  loadSessionRuntime: () => Promise<MovePlacementSessionRuntime>;
+}) {
+  return async (
+    identity: Pick<WorkerPlacementMoveRequest, "sessionId" | "sessionKey" | "agentId">,
+    moveTarget: WorkerPlacementMoveRequest["target"],
+  ): Promise<WorkerPlacementMoveDestination | undefined> => {
+    if (moveTarget.kind === "gateway") {
+      return undefined;
+    }
+    const sessionRuntime = await params.loadSessionRuntime();
+    const { config, target, entry } = resolveWorkerPlacementSessionTarget({
+      sessionRuntime,
+      config: params.getConfig(),
+      ...identity,
+      errorMessage: `Session ${identity.sessionKey} changed before placement move recovery.`,
+    });
+    const destination = resolveWorkerPlacementDestination({
+      cfg: config,
+      ...(moveTarget.kind === "profile"
+        ? { profileId: moveTarget.profileId, machineClass: moveTarget.machineClass }
+        : { deviceId: moveTarget.deviceId }),
+    });
+    if (!destination.ok || !destination.value) {
+      throw new Error(destination.ok ? "worker move target is missing" : destination.error);
+    }
+    const runtime = sessionRuntime.resolveWorkerPlacementSessionRuntime({
+      cfg: config,
+      entry,
+      agentId: target.agentId,
+      sessionKey: target.canonicalKey,
+    });
+    const { executionMode, devicePlacement } =
+      sessionRuntime.resolveWorkerPlacementCapabilities(runtime);
+    if (!executionMode) {
+      throw new Error(`Runtime ${runtime} lacks cloud placement support`);
+    }
+    if (moveTarget.kind === "profile") {
+      if (!params.environments.supportsExecutionMode(moveTarget.profileId, executionMode)) {
+        throw new Error(
+          `worker profile ${moveTarget.profileId} does not support ${executionMode} placement; select a compatible worker provider`,
+        );
+      }
+      return { executionMode, ...destination.value };
+    }
+    const eligibility = await resolveDevicePlacementEligibility({
+      environmentService: params.environments,
+      deviceId: moveTarget.deviceId,
+      runtimeId: runtime,
+      requirement: devicePlacement,
+      config,
+    });
+    if (!eligibility.ok) {
+      throw new Error(eligibility.error);
+    }
+    return { executionMode, ...destination.value, ...(devicePlacement ? { devicePlacement } : {}) };
+  };
+}
diff --git a/src/gateway/server-worker-placement-startup.test.ts b/src/gateway/server-worker-placement-startup.test.ts
index 6c795a30bcfa..7b64452824b0 100644
--- a/src/gateway/server-worker-placement-startup.test.ts
+++ b/src/gateway/server-worker-placement-startup.test.ts
@@ -851,71 +851,6 @@ describe("worker placement move destination", () => {
       });
     },
   );
-
-  it("rejects a remote-exec paired-device move before reclaiming the active source", async () => {
-    runtimeFactoryMocks.createDiskSpace.mockReturnValue({
-      read: vi.fn(),
-      version: vi.fn(() => 0),
-      sweep: vi.fn().mockResolvedValue(undefined),
-    });
-    runtimeFactoryMocks.createDispatch.mockReturnValue({
-      dispatch: vi.fn(),
-      forceDestroyEnvironment: vi.fn(),
-      move: vi.fn(),
-      reclaim: vi.fn(),
-      reconcile: vi.fn(),
-      reconcileActive: vi.fn(),
-    });
-    createGatewayWorkerPlacementRuntime({
-      placements: { workspaceResultInstanceId: () => "gateway-test" } as never,
-      environments: {} as never,
-      gatewayNamespace: "gateway-test",
-      revokeSessionAuthority: vi.fn(),
-      warn: vi.fn(),
-    });
-    const dispatchOptions = runtimeFactoryMocks.createDispatch.mock.calls.at(-1)?.[0] as
-      | {
-          resolveMoveDestination: Parameters<
-            typeof createWorkerPlacementMoveService
-          >[0]["resolveDestination"];
-        }
-      | undefined;
-    if (!dispatchOptions) {
-      throw new Error("worker placement dispatch options were not captured");
-    }
-    const runMoveBarrier = vi.fn(async () => {
-      throw new Error("source placement barrier started");
-    });
-    const reclaimSource = vi.fn();
-    const dispatch = vi.fn();
-    const moves = createWorkerPlacementMoveService({
-      placements: { getPlacementMove: () => undefined } as never,
-      environments: { get: () => undefined },
-      runMoveBarrier,
-      dispatch,
-      reclaimSource,
-      validateAbandonSource: vi.fn(),
-      abandonSource: vi.fn(async () => {
-        throw new Error("unexpected source abandonment");
-      }),
-      resolveDestination: dispatchOptions.resolveMoveDestination,
-    });
-
-    await expect(
-      moves.move({
-        sessionId: "session-move-source",
-        sessionKey: "agent:main:move-source",
-        agentId: "main",
-        source: { generation: 4, environmentId: "environment-source", ownerEpoch: 2 },
-        target: { kind: "device", deviceId: "paired-build-mac" },
-      }),
-    ).rejects.toThrow(
-      'runtime codex cannot move to a paired device; select an agent/model route with agentRuntime.id "openclaw" (the embedded runtime), or move to an SSH-backed cloud worker provider',
-    );
-    expect(runMoveBarrier).not.toHaveBeenCalled();
-    expect(reclaimSource).not.toHaveBeenCalled();
-    expect(dispatch).not.toHaveBeenCalled();
-  });
 });
 
 describe("worker placement startup recovery authority", () => {
diff --git a/src/gateway/server-worker-placement-startup.ts b/src/gateway/server-worker-placement-startup.ts
index ac2c6fef64ca..7cf5e29e8519 100644
--- a/src/gateway/server-worker-placement-startup.ts
+++ b/src/gateway/server-worker-placement-startup.ts
@@ -16,6 +16,7 @@ import { createGitHubPublicationRuntime } from "./github-publication-runtime.js"
 import type { NodeWorkerSupervisorTransport } from "./node-registry-private.js";
 import { emitSessionsChanged } from "./server-methods/session-change-event.js";
 import { createGatewayWorkerPlacementMoveBarrier } from "./server-worker-placement-move-barrier.js";
+import { createGatewayWorkerPlacementMoveDestinationResolver } from "./server-worker-placement-move-destination.js";
 import { createGatewayWorkerPlacementReclaimBarriers } from "./server-worker-placement-reclaim.js";
 import { installWorkerPlacementReconcileGuard } from "./server-worker-placement-reconcile-guard.js";
 import { createWorkerPlacementSessionEvidenceResolver } from "./server-worker-placement-session-evidence.js";
@@ -25,9 +26,9 @@ import {
   WorkerDispatchTargetChangedError,
 } from "./server-worker-placement-session-target.js";
 import { createNodeWorkspaceRetainCoordinator } from "./worker-environments/node-workspace-retain-coordinator.js";
-import { resolveWorkerPlacementDestination } from "./worker-environments/placement-destination.js";
 import { createWorkerPlacementDiskSpaceMonitor } from "./worker-environments/placement-disk-space.js";
 import { coordinateWorkerPlacementDispatch } from "./worker-environments/placement-dispatch-coordinator.js";
+import type { WorkerDevicePlacementRequirementResolver } from "./worker-environments/placement-dispatch-startup.js";
 import { createWorkerPlacementDispatchService } from "./worker-environments/placement-dispatch.js";
 import { FORCED_WORKER_ABANDONMENT_ERROR } from "./worker-environments/placement-force-abandon.js";
 import { createWorkerPlacementRunnerAvailabilityReader } from "./worker-environments/placement-projector.js";
@@ -52,6 +53,7 @@ const loadWorkerPlacementSessionRuntimeModule = createLazyRuntimeModule(async ()
   return {
     resolveWorkerPlacementExecutionMode:
       placementSessionRuntime.resolveWorkerPlacementExecutionMode,
+    resolveWorkerPlacementCapabilities: placementSessionRuntime.resolveWorkerPlacementCapabilities,
     managedWorktrees,
     resolveWorkerPlacementSessionRuntime:
       placementSessionRuntime.resolveWorkerPlacementSessionRuntime,
@@ -162,6 +164,31 @@ export function createGatewayWorkerPlacementRuntime(
     });
     return worktree.path;
   };
+  const resolveDevicePlacementRequirement: WorkerDevicePlacementRequirementResolver = async (
+    identity,
+  ) => {
+    const sessionRuntime = await loadWorkerPlacementSessionRuntimeModule();
+    const { config, target, entry } = resolveWorkerPlacementSessionTarget({
+      sessionRuntime,
+      config: getRuntimeConfig(),
+      ...identity,
+      errorMessage: `Session ${identity.sessionKey} changed before paired-device recovery`,
+    });
+    const runtime = sessionRuntime.resolveWorkerPlacementSessionRuntime({
+      cfg: config,
+      entry,
+      agentId: target.agentId,
+      sessionKey: target.canonicalKey,
+    });
+    const { executionMode, devicePlacement } =
+      sessionRuntime.resolveWorkerPlacementCapabilities(runtime);
+    if (executionMode !== identity.executionMode || !devicePlacement) {
+      throw new Error(
+        `runtime ${runtime} no longer supports this paired-device placement; select a compatible runtime or continue on the Gateway`,
+      );
+    }
+    return devicePlacement;
+  };
   const resolveNodeWorkspaceBinding = async (binding: {
     environmentId: string;
     ownerEpoch: number;
@@ -193,6 +220,7 @@ export function createGatewayWorkerPlacementRuntime(
       placements: params.placements,
       environments: params.environments,
       runnerAvailability,
+      resolveDevicePlacementRequirement,
       ...workspaceConflictHandlers,
       ...reclaimBarriers,
       runLocalBarrier: async ({
@@ -359,45 +387,11 @@ export function createGatewayWorkerPlacementRuntime(
         }
       },
       runMoveBarrier,
-      resolveMoveDestination: async ({ sessionId, sessionKey, agentId }, moveTarget) => {
-        if (moveTarget.kind === "gateway") {
-          return undefined;
-        }
-        const sessionRuntime = await loadWorkerPlacementSessionRuntimeModule();
-        const { config, target, entry } = resolveWorkerPlacementSessionTarget({
-          sessionRuntime,
-          config: getRuntimeConfig(),
-          sessionId,
-          sessionKey,
-          agentId,
-          errorMessage: `Session ${sessionKey} changed before placement move recovery.`,
-        });
-        const destination = resolveWorkerPlacementDestination({
-          cfg: config,
-          ...(moveTarget.kind === "profile"
-            ? { profileId: moveTarget.profileId, machineClass: moveTarget.machineClass }
-            : { deviceId: moveTarget.deviceId }),
-        });
-        if (!destination.ok || !destination.value) {
-          throw new Error(destination.ok ? "worker move target is missing" : destination.error);
-        }
-        const runtime = sessionRuntime.resolveWorkerPlacementSessionRuntime({
-          cfg: config,
-          entry,
-          agentId: target.agentId,
-          sessionKey: target.canonicalKey,
-        });
-        const executionMode = sessionRuntime.resolveWorkerPlacementExecutionMode(runtime);
-        if (!executionMode) {
-          throw new Error(`Runtime ${runtime} lacks cloud placement support`);
-        }
-        if (moveTarget.kind === "device" && executionMode !== "worker-turn") {
-          throw new Error(
-            `runtime ${runtime} cannot move to a paired device; select an agent/model route with agentRuntime.id "openclaw" (the embedded runtime), or move to an SSH-backed cloud worker provider`,
-          );
-        }
-        return { executionMode, ...destination.value };
-      },
+      resolveMoveDestination: createGatewayWorkerPlacementMoveDestinationResolver({
+        environments: params.environments,
+        getConfig: getRuntimeConfig,
+        loadSessionRuntime: loadWorkerPlacementSessionRuntimeModule,
+      }),
       resolveWorkspacePath,
       workspaceOperations,
       prepareAcceptedWorkspacePublication,
@@ -433,6 +427,7 @@ export function createGatewayWorkerPlacementRuntime(
     redispatchReclaimed: createReclaimedPlacementRedispatch({
       environments: params.environments,
       dispatch: dispatchService.dispatch,
+      resolveDevicePlacementRequirement,
     }),
     workspaceOperations,
     prepareAcceptedWorkspacePublication,
diff --git a/src/gateway/server.models-voicewake-misc.test.ts b/src/gateway/server.models-voicewake-misc.test.ts
index 60c309682de7..a5eec0b53a83 100644
--- a/src/gateway/server.models-voicewake-misc.test.ts
+++ b/src/gateway/server.models-voicewake-misc.test.ts
@@ -105,6 +105,11 @@ type AgentCatalogFixtureEntry = {
   contextWindow?: number;
 };
 
+const OPENCLAW_DEVICE_PLACEMENT: NonNullable<GatewayAgentRuntime["devicePlacement"]> = {
+  requiredNodeCommands: [],
+  consumesWorkerSlot: true,
+};
+
 const buildAgentCatalogFixture = (): AgentCatalogFixtureEntry[] => [
   { id: "gpt-test-z", provider: "openai", contextWindow: 0 },
   {
@@ -150,6 +155,7 @@ const expectedSortedCatalog = (gptTestZTags?: string[]): ModelCatalogRpcEntry[]
       id: "openclaw",
       cloudPlacementSupported: true,
       cloudPlacementExecutionMode: "worker-turn",
+      devicePlacement: OPENCLAW_DEVICE_PLACEMENT,
       devicePlacementSupported: true,
       source: "implicit",
     },
@@ -164,6 +170,7 @@ const expectedSortedCatalog = (gptTestZTags?: string[]): ModelCatalogRpcEntry[]
       id: "openclaw",
       cloudPlacementSupported: true,
       cloudPlacementExecutionMode: "worker-turn",
+      devicePlacement: OPENCLAW_DEVICE_PLACEMENT,
       devicePlacementSupported: true,
       source: "implicit",
     },
@@ -797,6 +804,7 @@ describe("gateway server models + voicewake", () => {
               id: "openclaw",
               cloudPlacementSupported: true,
               cloudPlacementExecutionMode: "worker-turn",
+              devicePlacement: OPENCLAW_DEVICE_PLACEMENT,
               devicePlacementSupported: true,
               source: "implicit",
             },
@@ -855,6 +863,7 @@ describe("gateway server models + voicewake", () => {
             id: "openclaw",
             cloudPlacementSupported: true,
             cloudPlacementExecutionMode: "worker-turn",
+            devicePlacement: OPENCLAW_DEVICE_PLACEMENT,
             devicePlacementSupported: true,
             source: "implicit",
           },
@@ -880,6 +889,7 @@ describe("gateway server models + voicewake", () => {
             id: "openclaw",
             cloudPlacementSupported: true,
             cloudPlacementExecutionMode: "worker-turn",
+            devicePlacement: OPENCLAW_DEVICE_PLACEMENT,
             devicePlacementSupported: true,
             source: "implicit",
           },
diff --git a/src/gateway/server.worker-placement-startup-context.test.ts b/src/gateway/server.worker-placement-startup-context.test.ts
index 71fd595a24e4..39c61a8650d8 100644
--- a/src/gateway/server.worker-placement-startup-context.test.ts
+++ b/src/gateway/server.worker-placement-startup-context.test.ts
@@ -35,7 +35,7 @@ test(
       deviceId: "missing-device",
     });
     expect(dispatch.ok).toBe(false);
-    expect(dispatch.error?.message).toContain("session-owned managed worktree");
+    expect(dispatch.error?.message).toBe("device worker is not a paired node host: missing-device");
 
     const reset = await rpcReq(ws, "sessions.reset", { key: sessionKey });
     expect(reset).toMatchObject({ ok: true, payload: { key: sessionKey } });
diff --git a/src/gateway/worker-environments/device-placement-eligibility.ts b/src/gateway/worker-environments/device-placement-eligibility.ts
new file mode 100644
index 000000000000..ddfc27855646
--- /dev/null
+++ b/src/gateway/worker-environments/device-placement-eligibility.ts
@@ -0,0 +1,74 @@
+import type { DevicePlacementRequirement } from "../../agents/harness/types.js";
+import type { OpenClawConfig } from "../../config/types.openclaw.js";
+import { isNodeCommandAllowed, resolveNodeCommandAllowlist } from "../node-command-policy.js";
+import { deviceUnavailableText, resolveDeviceWorkerAvailability } from "./device-provider.js";
+
+type DevicePlacementEligibility = { ok: true } | { ok: false; error: string };
+
+export async function resolveDevicePlacementEligibility(params: {
+  environmentService: object | undefined;
+  deviceId: string;
+  runtimeId?: string;
+  requirement: DevicePlacementRequirement | undefined;
+  config: OpenClawConfig;
+  currentNode?: {
+    nodeId: string;
+    connId?: string;
+    pairingGeneration?: string;
+    platform?: string;
+    deviceFamily?: string;
+  };
+}): Promise<DevicePlacementEligibility> {
+  const { deviceId, requirement } = params;
+  if (!requirement) {
+    return {
+      ok: false,
+      error: `runtime ${params.runtimeId ?? "selection"} does not support paired-device placement; select a compatible runtime or cloud worker provider`,
+    };
+  }
+  const availability = await resolveDeviceWorkerAvailability(params.environmentService, deviceId);
+  if (!availability.available || !availability.node) {
+    return { ok: false, error: deviceUnavailableText(deviceId, availability) };
+  }
+  const node = availability.node;
+  if (
+    params.currentNode &&
+    (params.currentNode.nodeId !== node.nodeId ||
+      (params.currentNode.connId && params.currentNode.connId !== node.connId) ||
+      (params.currentNode.pairingGeneration &&
+        params.currentNode.pairingGeneration !== node.pairingGeneration))
+  ) {
+    return {
+      ok: false,
+      error: deviceUnavailableText(deviceId, {
+        available: false,
+        unavailableReason: "disconnected",
+      }),
+    };
+  }
+  const declaredCommands = [...node.commands];
+  const allowlist = resolveNodeCommandAllowlist(params.config, {
+    ...(params.currentNode?.platform ? { platform: params.currentNode.platform } : {}),
+    ...(params.currentNode?.deviceFamily ? { deviceFamily: params.currentNode.deviceFamily } : {}),
+    commands: declaredCommands,
+    approvedCommands: declaredCommands,
+  });
+  for (const command of requirement.requiredNodeCommands) {
+    if (!isNodeCommandAllowed({ command, declaredCommands, allowlist }).ok) {
+      return {
+        ok: false,
+        error: `paired-device command ${command} is not enabled or approved for ${deviceId}; enable it in gateway.nodes.commands.allow and approve the command on the node`,
+      };
+    }
+  }
+  if (requirement.consumesWorkerSlot && node.workerHost.capacity.available <= 0) {
+    return {
+      ok: false,
+      error: deviceUnavailableText(deviceId, {
+        available: false,
+        unavailableReason: "at-capacity",
+      }),
+    };
+  }
+  return { ok: true };
+}
diff --git a/src/gateway/worker-environments/device-provider.test.ts b/src/gateway/worker-environments/device-provider.test.ts
index 4168088f4d16..2d113a43a0ee 100644
--- a/src/gateway/worker-environments/device-provider.test.ts
+++ b/src/gateway/worker-environments/device-provider.test.ts
@@ -95,7 +95,7 @@ describe("device worker provider", () => {
       listCurrentNodes: async () => [connectedNode()],
     }).provider;
 
-    expect(provider.supportedExecutionModes).toEqual(["worker-turn"]);
+    expect(provider.supportedExecutionModes).toEqual(["worker-turn", "remote-exec"]);
     const first = await provider.provision({ device: DEVICE_ID }, "operation-1");
     const repeated = await provider.provision({ device: DEVICE_ID }, "operation-1");
     const next = await provider.provision({ device: DEVICE_ID }, "operation-2");
@@ -109,6 +109,20 @@ describe("device worker provider", () => {
     expect(next.leaseId).not.toBe(first.leaseId);
   });
 
+  it("keeps a connected paired host available when all worker slots are occupied", async () => {
+    const runtime = deviceRuntime({
+      getPairedDevice: async () => pairedDevice(),
+      listCurrentNodes: async () => [connectedNode(DEVICE_ID, false)],
+    });
+
+    await expect(runtime.resolveAvailability(DEVICE_ID)).resolves.toMatchObject({
+      available: true,
+    });
+    await expect(runtime.provider.provision({ device: DEVICE_ID }, "remote-exec")).resolves.toEqual(
+      expect.objectContaining({ node: { deviceId: DEVICE_ID }, sharedHost: true }),
+    );
+  });
+
   it.each([
     {
       name: "missing pairing",
@@ -122,12 +136,6 @@ describe("device worker provider", () => {
       listCurrentNodes: async () => [],
       expectedMessage: `device worker node is not connected: ${DEVICE_ID}; reconnect it before retrying`,
     },
-    {
-      name: "connected node at capacity",
-      getPairedDevice: async () => pairedDevice(),
-      listCurrentNodes: async () => [connectedNode(DEVICE_ID, false)],
-      expectedMessage: `device worker is at capacity (all worker slots in use): ${DEVICE_ID}; retry after a running turn completes`,
-    },
   ])(
     "rejects $name during provision",
     async ({ getPairedDevice, listCurrentNodes, expectedMessage }) => {
diff --git a/src/gateway/worker-environments/device-provider.ts b/src/gateway/worker-environments/device-provider.ts
index d7446f7a3b1c..58ec6dd2c070 100644
--- a/src/gateway/worker-environments/device-provider.ts
+++ b/src/gateway/worker-environments/device-provider.ts
@@ -27,6 +27,7 @@ type DeviceWorkerRuntimeOptions = {
 
 export type DeviceWorkerAvailability = {
   available: boolean;
+  node?: NodeWorkerSupervisorNodeProof;
   issue?: NodeRunnerInventoryIssue;
   unavailableReason?: "unpaired" | "disconnected" | "at-capacity";
 };
@@ -89,10 +90,6 @@ function requireDeviceId(profile: WorkerProfile): string {
   return deviceId.trim();
 }
 
-function isSessionCapableNode(node: NodeWorkerSupervisorNodeProof): boolean {
-  return node.workerHost.capacity.available > 0;
-}
-
 function hasPairedNodeRole(device: PairedDevice | null): device is PairedDevice {
   return Boolean(device && hasEffectivePairedDeviceRole(device, "node"));
 }
@@ -122,24 +119,24 @@ export function createDeviceWorkerRuntime(options: DeviceWorkerRuntimeOptions) {
       options.getPairedDevice(deviceId),
       findConnectedNode(deviceId),
     ]);
-    // Connected hosts remain discoverable while full; capacity gates only new leases.
+    const current = connected && nodeTransport?.isCurrent(connected) ? connected : undefined;
+    // Transport availability is runtime-neutral; only worker-turn placement consumes a slot.
     const unavailableReason = !hasPairedNodeRole(paired)
       ? "unpaired"
-      : !connected
+      : !current
         ? "disconnected"
-        : !isSessionCapableNode(connected)
-          ? "at-capacity"
-          : undefined;
+        : undefined;
     const issue = nodeTransport?.getIssue?.(deviceId);
     return {
       available: unavailableReason === undefined,
+      ...(unavailableReason === undefined && current ? { node: current } : {}),
       ...(issue ? { issue } : {}),
       ...(unavailableReason ? { unavailableReason } : {}),
     };
   };
-  const provider: WorkerProvider = {
+  const provider: WorkerProvider<"internal"> = {
     id: DEVICE_WORKER_PROVIDER_ID,
-    supportedExecutionModes: ["worker-turn"],
+    supportedExecutionModes: ["worker-turn", "remote-exec"],
     provisionBeforeInstallation: true,
     provision: async (profile, operationId) => {
       const deviceId = requireDeviceId(profile);
diff --git a/src/gateway/worker-environments/environment-access.ts b/src/gateway/worker-environments/environment-access.ts
index 26a1012e1472..95f73af48fc5 100644
--- a/src/gateway/worker-environments/environment-access.ts
+++ b/src/gateway/worker-environments/environment-access.ts
@@ -27,12 +27,12 @@ type WorkerEnvironmentAccessOptions = {
   now: () => number;
   identityResolverFor: (
     record: WorkerEnvironmentRecord,
-    provider: WorkerProvider,
+    provider: WorkerProvider<"internal">,
     leaseId: string,
   ) => Parameters<WorkerTunnelManager["start"]>[0]["resolveIdentity"];
   inState: (record: WorkerEnvironmentRecord, ...states: WorkerEnvironmentState[]) => boolean;
   isStopping: () => boolean;
-  providerFor: (providerId: string) => WorkerProvider;
+  providerFor: (providerId: string) => WorkerProvider<"internal">;
   serviceError: (
     code:
       | "desktop_app_not_found"
diff --git a/src/gateway/worker-environments/identity.ts b/src/gateway/worker-environments/identity.ts
index 12e4429407ae..bfe34c95aa88 100644
--- a/src/gateway/worker-environments/identity.ts
+++ b/src/gateway/worker-environments/identity.ts
@@ -31,7 +31,7 @@ function requireIdentity(value: unknown): WorkerSshIdentity {
 
 /** Routes dynamic identities to their provider owner and configured refs to the generic resolver. */
 export async function resolveWorkerSshIdentity(params: {
-  provider: WorkerProvider;
+  provider: WorkerProvider<"internal">;
   leaseId: string;
   profile: WorkerProfile;
   keyRef: SecretRef;
diff --git a/src/gateway/worker-environments/node-worker-tunnel.ts b/src/gateway/worker-environments/node-worker-tunnel.ts
index 4f6348de8989..b881889aac2f 100644
--- a/src/gateway/worker-environments/node-worker-tunnel.ts
+++ b/src/gateway/worker-environments/node-worker-tunnel.ts
@@ -29,11 +29,12 @@ import {
 import type { NodeWorkspaceTransferService } from "./node-workspace-transfer-service.js";
 import type { WorkerSessionTurnClaim } from "./placement-record.js";
 import type { WorkerEnvironmentRecord } from "./store.js";
-import type {
-  WorkerTunnelStatus,
-  WorkerTurnLaunchRequest,
-  WorkerTurnTunnelHandle,
-  WorkerWorkspaceCommand,
+import {
+  WorkerTunnelOwnerDisconnectedError,
+  type WorkerTunnelStatus,
+  type WorkerTurnLaunchRequest,
+  type WorkerTurnTunnelHandle,
+  type WorkerWorkspaceCommand,
 } from "./tunnel-contract.js";
 import { boundedWorkerError } from "./worker-error.js";
 import { serializeWorkerWorkspaceManifest } from "./workspace-manifest.js";
@@ -210,10 +211,7 @@ export function createNodeWorkerTunnelManager(options: NodeWorkerTunnelManagerOp
   const findNode = async (
     entry: NodeTunnelEntry,
     signal: AbortSignal,
-  ): Promise<{
-    transport: NodeWorkerSupervisorTransport;
-    node: NodeWorkerSupervisorNodeProof;
-  }> => {
+  ): Promise<{ transport: NodeWorkerSupervisorTransport; node: NodeWorkerSupervisorNodeProof }> => {
     const transport = options.getTransport();
     if (!transport) {
       throw new Error("device worker node transport is unavailable");
@@ -222,7 +220,9 @@ export function createNodeWorkerTunnelManager(options: NodeWorkerTunnelManagerOp
       (candidate) => candidate.nodeId === entry.deviceId,
     );
     if (!node) {
-      throw new Error("device worker node is not connected with the supervisor dialect");
+      throw new WorkerTunnelOwnerDisconnectedError(
+        "device worker node is not connected with the supervisor dialect",
+      );
     }
     return { transport, node };
   };
diff --git a/src/gateway/worker-environments/placement-dispatch-device.test.ts b/src/gateway/worker-environments/placement-dispatch-device.test.ts
index 424ec9eca094..fade5a746cdf 100644
--- a/src/gateway/worker-environments/placement-dispatch-device.test.ts
+++ b/src/gateway/worker-environments/placement-dispatch-device.test.ts
@@ -1,18 +1,61 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  GATEWAY_CLIENT_IDS,
+  GATEWAY_CLIENT_MODES,
+} from "../../../packages/gateway-protocol/src/client-info.js";
 import { WORKER_EXECUTION_CONTEXT_PROTOCOL_FEATURE } from "../../../packages/gateway-protocol/src/schema/worker-admission.js";
 import { useAutoCleanupTempDirTracker } from "../../../test/helpers/temp-dir.js";
-import { NODE_RUNNER_UPDATE_REQUIRED_ISSUE } from "../../infra/node-runner-inventory.js";
+import {
+  NODE_RUNNER_UPDATE_REQUIRED_ISSUE,
+  NODE_WORKER_SUPERVISOR_PROTOCOL_FEATURE,
+} from "../../infra/node-runner-inventory.js";
 import {
   closeOpenClawStateDatabaseForTest,
   openOpenClawStateDatabase,
   type OpenClawStateDatabase,
 } from "../../state/openclaw-state-db.js";
+import type { NodeWorkerSupervisorNodeProof } from "../node-registry-private.js";
+import { resolveDevicePlacementEligibility } from "./device-placement-eligibility.js";
 import { bindDeviceWorkerAvailability } from "./device-provider.js";
 import { REQUEST, type PlacementStore } from "./placement-dispatch-test-fixtures.js";
 import { createHarness } from "./placement-dispatch-test-harness.js";
 import { createWorkerSessionPlacementStore } from "./placement-store.js";
 
+vi.mock("../../config/config.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../config/config.js")>();
+  return {
+    ...actual,
+    getRuntimeConfig: () => ({
+      ...actual.getRuntimeConfig(),
+      gateway: { nodes: { commands: { allow: ["codex.exec-server.stdio.v1"] } } },
+    }),
+  };
+});
+
 const tempDirs = useAutoCleanupTempDirTracker(afterEach);
+const CODEX_COMMAND = "codex.exec-server.stdio.v1";
+const OPENCLAW_DEVICE_REQUIREMENT = { requiredNodeCommands: [], consumesWorkerSlot: true };
+const CODEX_DEVICE_REQUIREMENT = {
+  requiredNodeCommands: [CODEX_COMMAND],
+  consumesWorkerSlot: false,
+};
+
+function deviceProof(
+  available = 2,
+  commands = ["system.run", CODEX_COMMAND],
+): NodeWorkerSupervisorNodeProof {
+  return {
+    nodeId: "device-1",
+    connId: "conn-device-1",
+    pairingIdentity: "identity-device-1",
+    pairingGeneration: "generation-device-1",
+    clientId: GATEWAY_CLIENT_IDS.NODE_HOST,
+    clientMode: GATEWAY_CLIENT_MODES.NODE,
+    protocolFeature: NODE_WORKER_SUPERVISOR_PROTOCOL_FEATURE,
+    workerHost: { enabled: true as const, capacity: { total: 2, available } },
+    commands,
+  };
+}
 
 describe("device worker placement dispatch", () => {
   let root: string;
@@ -31,7 +74,10 @@ describe("device worker placement dispatch", () => {
 
   it("provisions, syncs, and activates a local-install device environment", async () => {
     const harness = createHarness(placementStore);
-    bindDeviceWorkerAvailability(harness.environments, async () => ({ available: true }));
+    bindDeviceWorkerAvailability(harness.environments, async () => ({
+      available: true,
+      node: deviceProof(),
+    }));
     vi.mocked(harness.environments.createFromProfileSnapshot).mockResolvedValue({
       ...harness.ready,
       providerId: "device",
@@ -52,6 +98,7 @@ describe("device worker placement dispatch", () => {
       ...REQUEST,
       profileId: "device:device-1",
       deviceId: "device-1",
+      devicePlacement: OPENCLAW_DEVICE_REQUIREMENT,
       inheritedProfile: {
         providerId: "device",
         profileSnapshot: { install: "bundle" as const, settings: { device: "device-1" } },
@@ -83,6 +130,58 @@ describe("device worker placement dispatch", () => {
     expect(harness.placements.current()).toMatchObject({ state: "active" });
   });
 
+  it("syncs paired-device remote-exec without launching an OpenClaw worker child", async () => {
+    const harness = createHarness(placementStore);
+    bindDeviceWorkerAvailability(harness.environments, async () => ({
+      available: true,
+      node: deviceProof(0),
+    }));
+    vi.mocked(harness.environments.createFromProfileSnapshot).mockResolvedValue({
+      ...harness.ready,
+      providerId: "device",
+      profileId: "device:device-1",
+      profileSnapshot: { install: "bundle", settings: { device: "device-1" } },
+      nodeDeviceId: "device-1",
+      leaseId: "device-lease-1",
+      sshEndpoint: null,
+      sharedHost: true,
+    });
+    const request = {
+      ...REQUEST,
+      executionMode: "remote-exec" as const,
+      profileId: "device:device-1",
+      deviceId: "device-1",
+      devicePlacement: CODEX_DEVICE_REQUIREMENT,
+      inheritedProfile: {
+        providerId: "device",
+        profileSnapshot: { install: "bundle" as const, settings: { device: "device-1" } },
+      },
+    };
+
+    await expect(harness.service.dispatch(request)).resolves.toMatchObject({
+      state: "active",
+      executionMode: "remote-exec",
+      remoteWorkspaceDir: "/worker/workspace",
+    });
+
+    expect(harness.environments.createFromProfileSnapshot).toHaveBeenCalledWith(
+      { profileId: request.profileId, ...request.inheritedProfile },
+      expect.stringMatching(/^session-dispatch:/u),
+      undefined,
+      "remote-exec",
+    );
+    const workspaceTunnel = await vi.mocked(harness.environments.startTunnel).mock.results[0]
+      ?.value;
+    expect(workspaceTunnel?.syncWorkspace).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionId: request.sessionId,
+        localPath: expect.any(String),
+        generation: expect.any(Number),
+      }),
+    );
+    expect(workspaceTunnel?.launchTurn).not.toHaveBeenCalled();
+  });
+
   it("records an unavailable device dispatch as a durable failed placement", async () => {
     const harness = createHarness(placementStore);
     bindDeviceWorkerAvailability(harness.environments, async () => ({
@@ -94,6 +193,7 @@ describe("device worker placement dispatch", () => {
       ...REQUEST,
       profileId: "device:offline-device",
       deviceId: "offline-device",
+      devicePlacement: OPENCLAW_DEVICE_REQUIREMENT,
       inheritedProfile: {
         providerId: "device",
         profileSnapshot: {
@@ -120,6 +220,140 @@ describe("device worker placement dispatch", () => {
     });
   });
 
+  it("rechecks a paired node immediately before provisioning after its eligibility changes", async () => {
+    const harness = createHarness(placementStore);
+    const resolveAvailability = vi
+      .fn()
+      .mockResolvedValueOnce({ available: true, node: deviceProof() })
+      .mockResolvedValueOnce({ available: false, unavailableReason: "disconnected" });
+    bindDeviceWorkerAvailability(harness.environments, resolveAvailability);
+    const request = {
+      ...REQUEST,
+      profileId: "device:device-1",
+      deviceId: "device-1",
+      devicePlacement: OPENCLAW_DEVICE_REQUIREMENT,
+      inheritedProfile: {
+        providerId: "device",
+        profileSnapshot: { install: "bundle" as const, settings: { device: "device-1" } },
+      },
+    };
+
+    await expect(harness.service.dispatch(request)).rejects.toThrow("reconnect");
+
+    expect(resolveAvailability).toHaveBeenCalledTimes(2);
+    expect(harness.environments.createFromProfileSnapshot).not.toHaveBeenCalled();
+    expect(harness.environments.startTunnel).not.toHaveBeenCalled();
+    expect(harness.placements.current()).toMatchObject({
+      state: "failed",
+      environmentId: null,
+      recoveryError: expect.stringContaining("reconnect"),
+    });
+  });
+
+  it.each([
+    {
+      name: "allows remote-exec without a worker slot",
+      node: deviceProof(0),
+      requirement: CODEX_DEVICE_REQUIREMENT,
+      config: { gateway: { nodes: { commands: { allow: [CODEX_COMMAND] } } } },
+      expected: true,
+    },
+    {
+      name: "rejects worker-turn when all slots are occupied",
+      node: deviceProof(0),
+      requirement: OPENCLAW_DEVICE_REQUIREMENT,
+      config: {},
+      expected: false,
+      message: "at capacity",
+    },
+    {
+      name: "rejects an undeclared required command",
+      node: deviceProof(2, ["system.run"]),
+      requirement: CODEX_DEVICE_REQUIREMENT,
+      config: { gateway: { nodes: { commands: { allow: [CODEX_COMMAND] } } } },
+      expected: false,
+      message: "not enabled or approved",
+    },
+    {
+      name: "rejects a declared command denied by Gateway policy",
+      node: deviceProof(),
+      requirement: CODEX_DEVICE_REQUIREMENT,
+      config: { gateway: { nodes: { commands: { deny: [CODEX_COMMAND] } } } },
+      expected: false,
+      message: "not enabled or approved",
+    },
+    {
+      name: "allows an explicitly enabled declared command",
+      node: deviceProof(),
+      requirement: CODEX_DEVICE_REQUIREMENT,
+      config: { gateway: { nodes: { commands: { allow: [CODEX_COMMAND] } } } },
+      expected: true,
+    },
+    {
+      name: "rejects a replaced node connection",
+      node: deviceProof(),
+      requirement: OPENCLAW_DEVICE_REQUIREMENT,
+      config: {},
+      currentNode: { nodeId: "device-1", connId: "replaced-connection" },
+      expected: false,
+      message: "reconnect",
+    },
+  ])("$name", async ({ node, requirement, config, expected, ...scenario }) => {
+    const service = {};
+    bindDeviceWorkerAvailability(service, async () => ({ available: true, node }));
+
+    const result = await resolveDevicePlacementEligibility({
+      environmentService: service,
+      deviceId: "device-1",
+      requirement,
+      config,
+      ...("currentNode" in scenario ? { currentNode: scenario.currentNode } : {}),
+    });
+
+    expect(result.ok).toBe(expected);
+    if (!result.ok && "message" in scenario && scenario.message) {
+      expect(result.error).toContain(scenario.message);
+    }
+  });
+
+  it.each([
+    {
+      name: "saturated worker-turn node",
+      executionMode: "worker-turn" as const,
+      node: deviceProof(0),
+      expectedMessage: "at capacity",
+    },
+    {
+      name: "remote-exec node missing its required command",
+      executionMode: "remote-exec" as const,
+      node: deviceProof(0, ["system.run"]),
+      expectedMessage: "not enabled or approved",
+    },
+  ])("fences recovery of a $name before workspace sync", async (scenario) => {
+    const harness = createHarness(placementStore);
+    const provisioning = harness.placements.seedProvisioning(scenario.executionMode);
+    if (provisioning.state !== "provisioning") {
+      throw new Error("paired-device recovery fixture did not enter provisioning");
+    }
+    const environment = { ...harness.ready, providerId: "device", nodeDeviceId: "device-1" };
+    vi.mocked(harness.environments.get).mockImplementation((environmentId) =>
+      environmentId === environment.environmentId ? environment : undefined,
+    );
+    bindDeviceWorkerAvailability(harness.environments, async () => ({
+      available: true,
+      node: scenario.node,
+    }));
+
+    await harness.service.resumeProvisioning(provisioning, async () => {});
+
+    expect(harness.environments.attachSession).not.toHaveBeenCalled();
+    expect(harness.environments.startTunnel).not.toHaveBeenCalled();
+    expect(harness.placements.current()).toMatchObject({
+      state: "failed",
+      recoveryError: expect.stringContaining(scenario.expectedMessage),
+    });
+  });
+
   it("adopts an offline paired-device placement without eagerly starting its tunnel", async () => {
     const harness = createHarness(placementStore);
     await harness.environments.attachSession({
diff --git a/src/gateway/worker-environments/placement-dispatch-startup.ts b/src/gateway/worker-environments/placement-dispatch-startup.ts
index cdb3b60ce7ac..acafa920ebcd 100644
--- a/src/gateway/worker-environments/placement-dispatch-startup.ts
+++ b/src/gateway/worker-environments/placement-dispatch-startup.ts
@@ -1,4 +1,8 @@
+import type { DevicePlacementRequirement } from "../../agents/harness/types.js";
+import { getRuntimeConfig } from "../../config/config.js";
 import { supportsWorkerExecutionContextLaunch } from "./admission.js";
+import { resolveDevicePlacementEligibility } from "./device-placement-eligibility.js";
+import { DEVICE_WORKER_PROVIDER_ID } from "./device-provider-identity.js";
 import type {
   PlacementFailureActions,
   WorkerActivationBarrier,
@@ -24,6 +28,13 @@ export type WorkerPlacementRecoveryBarrier = (params: {
   run: (localPath: string) => Promise<void>;
 }) => Promise<void>;
 
+export type WorkerDevicePlacementRequirementResolver = (
+  identity: Pick<
+    WorkerPlacementDispatchRequest,
+    "sessionId" | "sessionKey" | "agentId" | "executionMode"
+  >,
+) => Promise<DevicePlacementRequirement>;
+
 function isPendingProvisioningEnvironment(
   environment: ReturnType<WorkerEnvironmentService["get"]>,
   environmentId: string | null,
@@ -67,6 +78,7 @@ export function createWorkerPlacementDispatchStartup(options: {
   runActivationBarrier: WorkerActivationBarrier;
   onActivated?: (request: WorkerPlacementDispatchRequest) => void;
   resolveGitAuthor?: (agentId: string) => { name?: string; email?: string } | undefined;
+  resolveDevicePlacementRequirement?: WorkerDevicePlacementRequirementResolver;
   reportTransition: (
     observer: ((placement: WorkerDispatchPlacement) => void) | undefined,
     placement: WorkerDispatchPlacement,
@@ -253,6 +265,27 @@ export function createWorkerPlacementDispatchStartup(options: {
             if (isPendingProvisioningEnvironment(environment, environmentId)) {
               return;
             }
+            let devicePlacement: DevicePlacementRequirement | undefined;
+            if (environment.providerId === DEVICE_WORKER_PROVIDER_ID && environment.nodeDeviceId) {
+              if (!options.resolveDevicePlacementRequirement) {
+                throw new Error("Paired-device recovery has no authoritative runtime requirement");
+              }
+              devicePlacement = await options.resolveDevicePlacementRequirement({
+                sessionId: placement.sessionId,
+                sessionKey: placement.sessionKey,
+                agentId: placement.agentId,
+                executionMode: placement.executionMode,
+              });
+              const eligibility = await resolveDevicePlacementEligibility({
+                environmentService: environments,
+                deviceId: environment.nodeDeviceId,
+                requirement: devicePlacement,
+                config: getRuntimeConfig(),
+              });
+              if (!eligibility.ok) {
+                throw new Error(eligibility.error);
+              }
+            }
             await continueProvisionedDispatch({
               request: {
                 sessionId: placement.sessionId,
@@ -260,7 +293,9 @@ export function createWorkerPlacementDispatchStartup(options: {
                 agentId: placement.agentId,
                 profileId: environment.profileId,
                 executionMode: placement.executionMode,
-                ...(environment.nodeDeviceId ? { deviceId: environment.nodeDeviceId } : {}),
+                ...(environment.providerId === DEVICE_WORKER_PROVIDER_ID && environment.nodeDeviceId
+                  ? { deviceId: environment.nodeDeviceId, devicePlacement }
+                  : {}),
               },
               placement: current,
               environment,
diff --git a/src/gateway/worker-environments/placement-dispatch-test-harness.ts b/src/gateway/worker-environments/placement-dispatch-test-harness.ts
index 9a56bbb53701..f9a7cbb4a354 100644
--- a/src/gateway/worker-environments/placement-dispatch-test-harness.ts
+++ b/src/gateway/worker-environments/placement-dispatch-test-harness.ts
@@ -414,8 +414,20 @@ export function createHarness(
         : {
             profileId: target.kind === "profile" ? target.profileId : `device:${target.deviceId}`,
             executionMode: REQUEST.executionMode,
-            ...(target.kind === "device" ? { deviceId: target.deviceId } : {}),
+            ...(target.kind === "device"
+              ? {
+                  deviceId: target.deviceId,
+                  devicePlacement: { requiredNodeCommands: [], consumesWorkerSlot: true },
+                }
+              : {}),
           },
+    resolveDevicePlacementRequirement: async ({ executionMode }) =>
+      executionMode === "remote-exec"
+        ? {
+            requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+            consumesWorkerSlot: false,
+          }
+        : { requiredNodeCommands: [], consumesWorkerSlot: true },
     runReclaimBarrier: async ({ authorize, begin, reclaim }) => {
       authorize?.();
       return await reclaim(options.workspacePath ?? "/gateway/workspace", begin());
@@ -442,7 +454,8 @@ export function createHarness(
     reconciledManifestRef,
     placements: {
       current: () => placementStore.get(REQUEST.sessionId),
-      seedProvisioning: () => seedProvisioningPlacement(placementStore, environmentId),
+      seedProvisioning: (executionMode?: "worker-turn" | "remote-exec") =>
+        seedProvisioningPlacement(placementStore, environmentId, executionMode),
       seedStarting: () => seedStartingPlacement(placementStore, environmentId),
       seedActive: (ownerEpoch: number, executionMode?: "worker-turn" | "remote-exec") =>
         seedActivePlacement(placementStore, { environmentId, ownerEpoch, executionMode }),
diff --git a/src/gateway/worker-environments/placement-dispatch.ts b/src/gateway/worker-environments/placement-dispatch.ts
index 894135ebc20c..fee0758e5c4b 100644
--- a/src/gateway/worker-environments/placement-dispatch.ts
+++ b/src/gateway/worker-environments/placement-dispatch.ts
@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
-import * as device from "./device-provider.js";
+import { getRuntimeConfig } from "../../config/config.js";
+import { resolveDevicePlacementEligibility } from "./device-placement-eligibility.js";
 import {
   createPlacementFailureActions,
   type WorkerActivationBarrier,
@@ -11,6 +12,7 @@ import {
 import { createPlacementRecoveryActions } from "./placement-dispatch-recovery.js";
 import {
   createWorkerPlacementDispatchStartup,
+  type WorkerDevicePlacementRequirementResolver,
   type WorkerPlacementRecoveryBarrier,
 } from "./placement-dispatch-startup.js";
 import { createWorkerPlacementMoveAbandonment } from "./placement-move-abandon.js";
@@ -124,6 +126,7 @@ type WorkerPlacementDispatchOptions = WorkerPlacementReclaimBarriers & {
     claim: import("./placement-store.js").WorkerSessionTurnClaim,
   ) => Promise<void>;
   resolveGitAuthor?: (agentId: string) => { name?: string; email?: string } | undefined;
+  resolveDevicePlacementRequirement?: WorkerDevicePlacementRequirementResolver;
 };
 
 function isExactAttachedEnvironment(
@@ -164,6 +167,7 @@ export function createWorkerPlacementDispatchService(options: WorkerPlacementDis
     runActivationBarrier: options.runActivationBarrier,
     onActivated: options.onActivated,
     resolveGitAuthor: options.resolveGitAuthor,
+    resolveDevicePlacementRequirement: options.resolveDevicePlacementRequirement,
     reportTransition,
   });
 
@@ -190,6 +194,20 @@ export function createWorkerPlacementDispatchService(options: WorkerPlacementDis
     authorize?: WorkerPlacementAuthorization,
   ): Promise<WorkerActiveDispatchPlacement> => {
     let placement: WorkerDispatchPlacement | undefined;
+    const validateDevicePlacement = async () => {
+      if (!request.deviceId) {
+        return;
+      }
+      const eligibility = await resolveDevicePlacementEligibility({
+        environmentService: environments,
+        deviceId: request.deviceId,
+        requirement: request.devicePlacement,
+        config: getRuntimeConfig(),
+      });
+      if (!eligibility.ok) {
+        throw new Error(eligibility.error);
+      }
+    };
     try {
       placement = await options.runLocalBarrier({
         sessionId: request.sessionId,
@@ -208,16 +226,10 @@ export function createWorkerPlacementDispatchService(options: WorkerPlacementDis
           return placement;
         },
       });
-      if (request.deviceId) {
-        const availability = await device.resolveDeviceWorkerAvailability(
-          environments,
-          request.deviceId,
-        );
-        if (!availability.available) {
-          throw new Error(device.deviceUnavailableText(request.deviceId, availability));
-        }
-      }
+      await validateDevicePlacement();
       const localPath = await options.resolveWorkspacePath(request);
+      // Workspace preparation yields; fence the current paired node again before durable provision.
+      await validateDevicePlacement();
       const idempotencyKey =
         request.idempotencyKey ?? `session-dispatch:${request.sessionId}:${placement.generation}`;
       const expectedEnvironmentId = deriveEnvironmentIntent(idempotencyKey).environmentId;
diff --git a/src/gateway/worker-environments/placement-force-abandon.ts b/src/gateway/worker-environments/placement-force-abandon.ts
index 2ba9be2e1bce..3f224202abdd 100644
--- a/src/gateway/worker-environments/placement-force-abandon.ts
+++ b/src/gateway/worker-environments/placement-force-abandon.ts
@@ -156,6 +156,7 @@ export async function forceAbandonWorkerEnvironment(params: {
         environmentId: current.environmentId,
         ownerEpoch: current.activeOwnerEpoch,
         expectedGeneration: current.generation,
+        forceLocalClaim: true,
       });
     }
     if (current && current.state !== "failed") {
diff --git a/src/gateway/worker-environments/placement-move-abandon.test.ts b/src/gateway/worker-environments/placement-move-abandon.test.ts
index 80f69ba3bc93..96fe34d7a527 100644
--- a/src/gateway/worker-environments/placement-move-abandon.test.ts
+++ b/src/gateway/worker-environments/placement-move-abandon.test.ts
@@ -150,6 +150,55 @@ describe("offline device placement abandonment", () => {
     expect(beforeMoveBegin).toHaveBeenCalledOnce();
   });
 
+  it("forces an offline remote-exec device onto the Gateway without waiting for its local claim", async () => {
+    const harness = createHarness(placements);
+    const active = await harness.service.dispatch({ ...REQUEST, executionMode: "remote-exec" });
+    harness.markEnvironmentNodeDeviceId("device-1");
+    seedEnvironment(active);
+    const claim = placements.claimTurn({
+      sessionId: active.sessionId,
+      sessionKey: active.sessionKey,
+      agentId: active.agentId,
+      claimId: "offline-remote-exec-claim",
+      runId: "offline-remote-exec-run",
+      owner: {
+        kind: "local",
+        environmentId: active.environmentId,
+        ownerEpoch: active.activeOwnerEpoch,
+      },
+    });
+    const closeToolState = vi.spyOn(placements, "closeWorkerTurnToolState");
+    const closed = vi.fn();
+    const unregister = placements.registerTurnClaimClosedHandler(closed);
+    vi.mocked(harness.environments.startTunnel).mockClear();
+
+    await expect(harness.service.move(requestFor(active))).resolves.toMatchObject({
+      state: "local",
+      turnClaim: null,
+    });
+
+    expect(closeToolState).toHaveBeenCalledExactlyOnceWith(claim);
+    expect(closed).toHaveBeenCalledExactlyOnceWith(claim);
+    expect(harness.environments.startTunnel).not.toHaveBeenCalled();
+    expect(harness.environments.destroy).toHaveBeenCalledOnce();
+    expect(harness.log).not.toContain("workspace:reconcile");
+    expect(placements.validateTurnClaim(claim)).toBe(false);
+    expect(placements.listPendingWorkspaceResults()).toEqual([]);
+    expect(placements.getPlacementMove(active.sessionId)).toBeUndefined();
+    expect(() =>
+      placements.startReconcile({
+        sessionId: active.sessionId,
+        environmentId: active.environmentId,
+        ownerEpoch: active.activeOwnerEpoch,
+        expectedGeneration: active.generation + 1,
+      }),
+    ).toThrow("Cannot reconcile stale worker placement");
+    expect(() => placements.releaseTurn(claim)).toThrow("turn claim changed before release");
+    expect(closeToolState).toHaveBeenCalledOnce();
+    expect(closed).toHaveBeenCalledOnce();
+    unregister();
+  });
+
   it("joins a durable abandonment retry without validating or persisting the source again", async () => {
     const persistedPartials: string[] = [];
     const beforeMoveBegin = vi.fn(async (abandoned: { runId: string } | undefined) => {
diff --git a/src/gateway/worker-environments/placement-sandbox.test.ts b/src/gateway/worker-environments/placement-sandbox.test.ts
index 438e61c04cd6..8fa3ea61abfe 100644
--- a/src/gateway/worker-environments/placement-sandbox.test.ts
+++ b/src/gateway/worker-environments/placement-sandbox.test.ts
@@ -1,68 +1,78 @@
+import path from "node:path";
 import { describe, expect, it, vi } from "vitest";
 import type { WorkerSessionPlacementRecord } from "./placement-record.js";
 import { createRemoteExecPlacementSandbox } from "./placement-sandbox.js";
 import type { WorkerEnvironmentService } from "./service.js";
 
+const environmentId = "worker:environment-1";
+const remoteWorkspaceDir = "/srv/openclaw/workspaces/session-1";
+
+function remoteExecPlacement() {
+  return {
+    state: "active",
+    executionMode: "remote-exec",
+    sessionId: "session-1",
+    sessionKey: "agent:main:session-1",
+    agentId: "main",
+    generation: 11,
+    turnClaim: null,
+    createdAtMs: 1,
+    updatedAtMs: 2,
+    stateChangedAtMs: 2,
+    environmentId,
+    activeOwnerEpoch: 7,
+    workspaceBaseManifestRef: `sha256:${"b".repeat(64)}`,
+    remoteWorkspaceDir,
+    workerBundleHash: "a".repeat(64),
+    lastTranscriptAckCursor: null,
+    lastLiveEventAckCursor: null,
+    recoveryError: null,
+    terminalReason: null,
+    terminalAtMs: null,
+  } satisfies Extract<WorkerSessionPlacementRecord, { state: "active" }>;
+}
+
+function attachedEnvironment() {
+  return {
+    environmentId,
+    providerId: "fake",
+    profileId: "development",
+    profileSnapshot: { settings: { region: "test" } },
+    provisionOperationId: "provision-1",
+    nodeSetupId: null,
+    nodeDeviceId: null,
+    sharedHost: false,
+    desktop: null,
+    bootstrapReceipt: null,
+    ownerEpoch: 7,
+    teardownTerminalState: null,
+    attachedSessionIds: ["session-1"],
+    lastError: null,
+    createdAtMs: 1,
+    updatedAtMs: 2,
+    stateChangedAtMs: 2,
+    idleSinceAtMs: null,
+    destroyRequestedAtMs: null,
+    state: "attached",
+    leaseId: "lease-1",
+    sshEndpoint: {
+      host: "worker.example.test",
+      port: 2202,
+      fallbackPorts: [22],
+      user: "worker",
+      hostKey: "ssh-ed25519 AAAA",
+      keyRef: { source: "file", provider: "worker-keys", id: "/key" },
+    },
+    desktopAvailable: false,
+    desktopApps: [],
+    tunnelStatus: "connected",
+  } satisfies NonNullable<ReturnType<WorkerEnvironmentService["get"]>>;
+}
+
 describe("remote-exec placement sandbox", () => {
-  it("binds the exact managed worktree and placement generation into the runtime", async () => {
-    const environmentId = "worker:environment-1";
-    const remoteWorkspaceDir = "/srv/openclaw/workspaces/session-1";
-    const placement = {
-      state: "active",
-      executionMode: "remote-exec",
-      sessionId: "session-1",
-      sessionKey: "agent:main:session-1",
-      agentId: "main",
-      generation: 11,
-      turnClaim: null,
-      createdAtMs: 1,
-      updatedAtMs: 2,
-      stateChangedAtMs: 2,
-      environmentId,
-      activeOwnerEpoch: 7,
-      workspaceBaseManifestRef: `sha256:${"b".repeat(64)}`,
-      remoteWorkspaceDir,
-      workerBundleHash: "a".repeat(64),
-      lastTranscriptAckCursor: null,
-      lastLiveEventAckCursor: null,
-      recoveryError: null,
-      terminalReason: null,
-      terminalAtMs: null,
-    } satisfies Extract<WorkerSessionPlacementRecord, { state: "active" }>;
-    const environment = {
-      environmentId,
-      providerId: "fake",
-      profileId: "development",
-      profileSnapshot: { settings: { region: "test" } },
-      provisionOperationId: "provision-1",
-      nodeSetupId: null,
-      nodeDeviceId: null,
-      sharedHost: false,
-      desktop: null,
-      bootstrapReceipt: null,
-      ownerEpoch: 7,
-      teardownTerminalState: null,
-      attachedSessionIds: [placement.sessionId],
-      lastError: null,
-      createdAtMs: 1,
-      updatedAtMs: 2,
-      stateChangedAtMs: 2,
-      idleSinceAtMs: null,
-      destroyRequestedAtMs: null,
-      state: "attached",
-      leaseId: "lease-1",
-      sshEndpoint: {
-        host: "worker.example.test",
-        port: 2202,
-        fallbackPorts: [22],
-        user: "worker",
-        hostKey: "ssh-ed25519 AAAA",
-        keyRef: { source: "file", provider: "worker-keys", id: "/key" },
-      },
-      desktopAvailable: false,
-      desktopApps: [],
-      tunnelStatus: "connected",
-    } satisfies NonNullable<ReturnType<WorkerEnvironmentService["get"]>>;
+  it("binds the exact SSH managed worktree and placement generation into the runtime", async () => {
+    const placement = remoteExecPlacement();
+    const environment = attachedEnvironment();
     const resolveSshIdentity = vi.fn(async () => ({
       kind: "material" as const,
       contents: "private-key-material",
@@ -85,5 +95,183 @@ describe("remote-exec placement sandbox", () => {
     });
     expect(sandbox.backend?.workdir).toBe(remoteWorkspaceDir);
     expect(sandbox.backend?.workdirRoots).toEqual([remoteWorkspaceDir]);
+    expect(sandbox).not.toHaveProperty("placementEnvironmentId");
+    expect(sandbox).not.toHaveProperty("placementSessionId");
+    expect(sandbox).not.toHaveProperty("placementOwnerEpoch");
   });
+
+  it.each([
+    { platform: "POSIX", nodeWorkspaceDir: remoteWorkspaceDir },
+    {
+      platform: "Windows",
+      nodeWorkspaceDir: path.win32.join(
+        "C:\\",
+        "Users",
+        "Node",
+        ".openclaw",
+        "node-host",
+        "workspaces",
+        "session-1",
+      ),
+    },
+  ])(
+    "binds an exact $platform paired-node worktree without inventing an SSH backend or filesystem bridge",
+    async ({ nodeWorkspaceDir }) => {
+      const placement = { ...remoteExecPlacement(), remoteWorkspaceDir: nodeWorkspaceDir };
+      const environment = {
+        ...attachedEnvironment(),
+        providerId: "device",
+        nodeDeviceId: "paired-node-1",
+        sharedHost: true,
+        sshEndpoint: null,
+      } satisfies NonNullable<ReturnType<WorkerEnvironmentService["get"]>>;
+      const resolveSshIdentity = vi.fn();
+
+      const sandbox = await createRemoteExecPlacementSandbox({
+        environments: { get: () => environment, resolveSshIdentity },
+        localWorkspaceDir: "/local/managed-worktree",
+        placement,
+      });
+
+      expect(sandbox).toMatchObject({
+        enabled: true,
+        placementExecutionMode: "remote-exec",
+        placementNodeId: "paired-node-1",
+        placementEnvironmentId: environmentId,
+        placementSessionId: "session-1",
+        placementOwnerEpoch: 7,
+        backendId: "node",
+        runtimeId: "remote-exec:worker:environment-1:7:11",
+        workspaceDir: "/local/managed-worktree",
+        containerWorkdir: nodeWorkspaceDir,
+      });
+      expect(sandbox.backend).toBeUndefined();
+      expect(sandbox.fsBridge).toBeUndefined();
+      expect(resolveSshIdentity).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each([
+    { label: "POSIX root", workspaceDir: "/" },
+    { label: "Windows root", workspaceDir: "C:\\" },
+    { label: "POSIX traversal", workspaceDir: "/srv/../workspace" },
+    { label: "Windows traversal", workspaceDir: String.raw`C:\Users\..\workspace` },
+    { label: "Windows drive-relative path", workspaceDir: "C:workspace" },
+    { label: "Windows rooted path without a drive", workspaceDir: String.raw`\workspace` },
+    { label: "Windows UNC path", workspaceDir: String.raw`\\server\share\workspace` },
+    { label: "mixed Windows separators", workspaceDir: String.raw`C:\Users/workspace` },
+    { label: "POSIX trailing separator", workspaceDir: "/srv/workspace/" },
+    { label: "Windows trailing separator", workspaceDir: "C:\\Users\\workspace\\" },
+  ])("rejects an ambiguous or noncanonical paired-node $label", async ({ workspaceDir }) => {
+    const environment = {
+      ...attachedEnvironment(),
+      nodeDeviceId: "paired-node-1",
+      sshEndpoint: null,
+    };
+
+    await expect(
+      createRemoteExecPlacementSandbox({
+        environments: { get: () => environment },
+        localWorkspaceDir: "/local/managed-worktree",
+        placement: { ...remoteExecPlacement(), remoteWorkspaceDir: workspaceDir },
+      }),
+    ).rejects.toThrow("invalid managed workspace path");
+  });
+
+  it("rejects Windows workspace paths for the POSIX SSH carrier", async () => {
+    const environment = attachedEnvironment();
+    const resolveSshIdentity = vi.fn();
+
+    await expect(
+      createRemoteExecPlacementSandbox({
+        environments: { get: () => environment, resolveSshIdentity },
+        localWorkspaceDir: "/local/managed-worktree",
+        placement: {
+          ...remoteExecPlacement(),
+          remoteWorkspaceDir: String.raw`C:\Users\Node\workspace`,
+        },
+      }),
+    ).rejects.toThrow("invalid managed workspace path");
+    expect(resolveSshIdentity).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    {
+      label: "stale owner epoch",
+      mutate: (environment: ReturnType<typeof attachedEnvironment>) => ({
+        ...environment,
+        ownerEpoch: environment.ownerEpoch + 1,
+      }),
+    },
+    {
+      label: "different attached session",
+      mutate: (environment: ReturnType<typeof attachedEnvironment>) => ({
+        ...environment,
+        attachedSessionIds: ["replacement-session"],
+      }),
+    },
+    {
+      label: "different SSH endpoint",
+      mutate: (environment: ReturnType<typeof attachedEnvironment>) => ({
+        ...environment,
+        sshEndpoint: { ...environment.sshEndpoint, host: "replacement.example.test" },
+      }),
+    },
+  ])("rejects a $label after awaited SSH identity preparation", async ({ mutate }) => {
+    const placement = remoteExecPlacement();
+    let environment = attachedEnvironment();
+    const resolveSshIdentity = vi.fn(async () => {
+      environment = mutate(environment);
+      return { kind: "material" as const, contents: "private-key-material" };
+    });
+
+    await expect(
+      createRemoteExecPlacementSandbox({
+        environments: { get: () => environment, resolveSshIdentity },
+        localWorkspaceDir: "/local/managed-worktree",
+        placement,
+      }),
+    ).rejects.toThrow("lost its exact environment");
+  });
+
+  it.each([
+    {
+      label: "node identity",
+      replacement: { nodeDeviceId: "replacement-node" },
+    },
+    {
+      label: "environment identity",
+      replacement: { environmentId: "worker:replacement-environment" },
+    },
+    {
+      label: "owner epoch",
+      replacement: { ownerEpoch: 8 },
+    },
+    {
+      label: "session identity",
+      replacement: { attachedSessionIds: ["replacement-session"] },
+    },
+  ])(
+    "rejects a paired node's replaced $label before returning its sandbox",
+    async ({ replacement }) => {
+      const placement = remoteExecPlacement();
+      const environment = {
+        ...attachedEnvironment(),
+        nodeDeviceId: "paired-node-1",
+        sshEndpoint: null,
+      };
+      const get = vi
+        .fn<WorkerEnvironmentService["get"]>()
+        .mockReturnValueOnce(environment)
+        .mockReturnValueOnce({ ...environment, ...replacement });
+
+      await expect(
+        createRemoteExecPlacementSandbox({
+          environments: { get },
+          localWorkspaceDir: "/local/managed-worktree",
+          placement,
+        }),
+      ).rejects.toThrow("lost its exact environment");
+    },
+  );
 });
diff --git a/src/gateway/worker-environments/placement-sandbox.ts b/src/gateway/worker-environments/placement-sandbox.ts
index 91bf75397682..d410a79c340a 100644
--- a/src/gateway/worker-environments/placement-sandbox.ts
+++ b/src/gateway/worker-environments/placement-sandbox.ts
@@ -1,4 +1,5 @@
 import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import { resolveSandboxConfigForAgent } from "../../agents/sandbox/config.js";
 import { createSandboxFsBridge } from "../../agents/sandbox/fs-bridge.js";
 import { createPreprovisionedSshSandboxBackend } from "../../agents/sandbox/ssh-backend.js";
@@ -10,30 +11,51 @@ import { resolveWorkerSshSandboxSettings } from "./ssh.js";
 
 type ActiveRemoteExecPlacement = Extract<WorkerSessionPlacementRecord, { state: "active" }>;
 
-type PlacementSandboxEnvironmentService = Pick<
-  WorkerEnvironmentService,
-  "get" | "resolveSshIdentity"
->;
+type PlacementSandboxEnvironmentService = Pick<WorkerEnvironmentService, "get"> &
+  Partial<Pick<WorkerEnvironmentService, "resolveSshIdentity">>;
 
-function requireRemoteWorkspaceDir(value: string): string {
+type RemoteExecPlacementSandbox = SandboxContext & {
+  placementExecutionMode: "remote-exec";
+} & (
+    | {
+        backendId: "node";
+        placementNodeId: string;
+        placementEnvironmentId: string;
+        placementSessionId: string;
+        placementOwnerEpoch: number;
+      }
+    | {
+        backendId: "ssh";
+        placementNodeId?: never;
+        placementEnvironmentId?: never;
+        placementSessionId?: never;
+        placementOwnerEpoch?: never;
+      }
+  );
+
+function requireRemoteWorkspaceDir(value: string, nodeCarrier: boolean): string {
+  // Paired nodes report their own native paths, which can differ from the Gateway platform.
+  const windowsPath = nodeCarrier && /^[A-Za-z]:/u.test(value) && value[2] === "\\";
+  const remotePath = windowsPath ? path.win32 : path.posix;
   if (
-    !path.posix.isAbsolute(value) ||
-    value === "/" ||
-    path.posix.normalize(value) !== value ||
-    value.endsWith("/")
+    !remotePath.isAbsolute(value) ||
+    remotePath.parse(value).root === value ||
+    remotePath.normalize(value) !== value ||
+    value.endsWith(remotePath.sep) ||
+    (nodeCarrier && (windowsPath ? value.includes("/") : value.includes("\\")))
   ) {
     throw new Error("Remote-exec placement has an invalid managed workspace path");
   }
   return value;
 }
 
-/** Builds the SSH sandbox owned by one exact active placement generation. */
+/** Builds the node or SSH sandbox owned by one exact active placement generation. */
 export async function createRemoteExecPlacementSandbox(params: {
   config?: OpenClawConfig;
   environments: PlacementSandboxEnvironmentService;
   localWorkspaceDir: string;
   placement: ActiveRemoteExecPlacement;
-}): Promise<SandboxContext & { placementExecutionMode: "remote-exec" }> {
+}): Promise<RemoteExecPlacementSandbox> {
   const { placement } = params;
   if (placement.executionMode !== "remote-exec") {
     throw new Error(`Cloud placement ${placement.sessionId} is not a remote-exec placement`);
@@ -47,16 +69,32 @@ export async function createRemoteExecPlacementSandbox(params: {
     environment.attachedSessionIds.length !== 1 ||
     environment.attachedSessionIds[0] !== placement.sessionId ||
     !environment.leaseId ||
-    !environment.sshEndpoint
+    Boolean(environment.nodeDeviceId) === Boolean(environment.sshEndpoint)
   ) {
     throw new Error(
-      `Remote-exec placement ${placement.sessionId} has no matching active SSH environment`,
+      `Remote-exec placement ${placement.sessionId} has no matching active node or SSH environment`,
     );
   }
 
-  const identity = await params.environments.resolveSshIdentity(environment.environmentId);
-  const ssh = resolveWorkerSshSandboxSettings({ ssh: environment.sshEndpoint, identity });
-  const remoteWorkspaceDir = requireRemoteWorkspaceDir(placement.remoteWorkspaceDir);
+  const assertCurrentEnvironment = () => {
+    const current = params.environments.get(environment.environmentId);
+    if (
+      current?.state !== "attached" ||
+      current.environmentId !== environment.environmentId ||
+      current.ownerEpoch !== environment.ownerEpoch ||
+      current.leaseId !== environment.leaseId ||
+      current.nodeDeviceId !== environment.nodeDeviceId ||
+      !isDeepStrictEqual(current.sshEndpoint, environment.sshEndpoint) ||
+      current.attachedSessionIds.length !== 1 ||
+      current.attachedSessionIds[0] !== placement.sessionId
+    ) {
+      throw new Error(`Remote-exec placement ${placement.sessionId} lost its exact environment`);
+    }
+  };
+  const remoteWorkspaceDir = requireRemoteWorkspaceDir(
+    placement.remoteWorkspaceDir,
+    Boolean(environment.nodeDeviceId),
+  );
   const runtimeId = [
     "remote-exec",
     environment.environmentId,
@@ -65,6 +103,41 @@ export async function createRemoteExecPlacementSandbox(params: {
   ].join(":");
   const base = resolveSandboxConfigForAgent(params.config, placement.agentId);
   const { binds: _ignoredBinds, ...docker } = base.docker;
+  const common = {
+    enabled: true,
+    placementExecutionMode: "remote-exec" as const,
+    sessionKey: placement.sessionKey,
+    workspaceDir: params.localWorkspaceDir,
+    agentWorkspaceDir: params.localWorkspaceDir,
+    workspaceAccess: "rw" as const,
+    runtimeId,
+    runtimeLabel: runtimeId,
+    containerName: runtimeId,
+    containerWorkdir: remoteWorkspaceDir,
+    docker,
+    tools: base.tools,
+    browserAllowHostControl: false,
+  };
+  if (environment.nodeDeviceId) {
+    // Node workspace ownership already belongs to the placement; JSON-RPC is its execution seam.
+    assertCurrentEnvironment();
+    return {
+      ...common,
+      backendId: "node",
+      placementNodeId: environment.nodeDeviceId,
+      placementEnvironmentId: environment.environmentId,
+      placementSessionId: placement.sessionId,
+      placementOwnerEpoch: environment.ownerEpoch,
+    };
+  }
+  const sshEndpoint = environment.sshEndpoint;
+  const resolveSshIdentity = params.environments.resolveSshIdentity;
+  if (!sshEndpoint || !resolveSshIdentity) {
+    throw new Error("Remote-exec SSH sandbox identity resolver is unavailable");
+  }
+  const identity = await resolveSshIdentity(environment.environmentId);
+  assertCurrentEnvironment();
+  const ssh = resolveWorkerSshSandboxSettings({ ssh: sshEndpoint, identity });
   const cfg: SandboxConfig = {
     ...base,
     mode: "all",
@@ -90,23 +163,8 @@ export async function createRemoteExecPlacementSandbox(params: {
     },
     { runtimeId, remoteWorkspaceDir },
   );
-  const sandbox: SandboxContext & { placementExecutionMode: "remote-exec" } = {
-    enabled: true,
-    placementExecutionMode: "remote-exec",
-    backendId: "ssh",
-    sessionKey: placement.sessionKey,
-    workspaceDir: params.localWorkspaceDir,
-    agentWorkspaceDir: params.localWorkspaceDir,
-    workspaceAccess: "rw",
-    runtimeId,
-    runtimeLabel: runtimeId,
-    containerName: runtimeId,
-    containerWorkdir: remoteWorkspaceDir,
-    docker: cfg.docker,
-    tools: cfg.tools,
-    browserAllowHostControl: false,
-    backend,
-  };
+  assertCurrentEnvironment();
+  const sandbox: RemoteExecPlacementSandbox = { ...common, backendId: "ssh", backend };
   sandbox.fsBridge = backend.createFsBridge?.({ sandbox }) ?? createSandboxFsBridge({ sandbox });
   return sandbox;
 }
diff --git a/src/gateway/worker-environments/placement-session-runtime.test.ts b/src/gateway/worker-environments/placement-session-runtime.test.ts
new file mode 100644
index 000000000000..d5cc6c17bb56
--- /dev/null
+++ b/src/gateway/worker-environments/placement-session-runtime.test.ts
@@ -0,0 +1,146 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { registerAgentHarness } from "../../agents/harness/registry.js";
+import type { AgentHarness } from "../../agents/harness/types.js";
+import { createEmptyPluginRegistry } from "../../plugins/registry-empty.js";
+import {
+  getActivePluginRegistry,
+  resetPluginRuntimeStateForTest,
+  setActivePluginRegistry,
+} from "../../plugins/runtime.js";
+import {
+  projectWorkerPlacementAgentRuntime,
+  resolveWorkerPlacementCapabilities,
+  resolveWorkerPlacementExecutionMode,
+} from "./placement-session-runtime.js";
+
+const originalPluginRegistry = getActivePluginRegistry();
+
+describe("worker placement runtime capabilities", () => {
+  beforeEach(() => {
+    setActivePluginRegistry(createEmptyPluginRegistry(), "placement-runtime-test", "default");
+  });
+
+  afterEach(() => {
+    if (originalPluginRegistry) {
+      setActivePluginRegistry(originalPluginRegistry, "placement-runtime-test-restore", "default");
+      return;
+    }
+    resetPluginRuntimeStateForTest();
+  });
+
+  it.each([
+    {
+      name: "embedded worker turns support paired devices",
+      runtimeId: "openclaw",
+      executionMode: "worker-turn",
+      devicePlacementSupported: true,
+      devicePlacement: { requiredNodeCommands: [], consumesWorkerSlot: true },
+    },
+    {
+      name: "remote execution projects exact device commands without consuming a worker slot",
+      runtimeId: "device-harness",
+      cloudPlacement: {
+        mode: "remote-exec",
+        devicePlacement: {
+          requiredNodeCommands: ["runtime.exec-server.v1"],
+          consumesWorkerSlot: false,
+        },
+      },
+      executionMode: "remote-exec",
+      devicePlacementSupported: true,
+      devicePlacement: {
+        requiredNodeCommands: ["runtime.exec-server.v1"],
+        consumesWorkerSlot: false,
+      },
+    },
+    {
+      name: "device command requirements are deterministic and deduplicated",
+      runtimeId: "ordered-harness",
+      cloudPlacement: {
+        mode: "remote-exec",
+        devicePlacement: {
+          requiredNodeCommands: ["runtime.zeta.v1", "runtime.alpha.v1", "runtime.zeta.v1"],
+          consumesWorkerSlot: false,
+        },
+      },
+      executionMode: "remote-exec",
+      devicePlacementSupported: true,
+      devicePlacement: {
+        requiredNodeCommands: ["runtime.alpha.v1", "runtime.zeta.v1"],
+        consumesWorkerSlot: false,
+      },
+    },
+    {
+      name: "cloud-only remote execution does not support paired devices",
+      runtimeId: "cloud-harness",
+      cloudPlacement: { mode: "remote-exec" },
+      executionMode: "remote-exec",
+      devicePlacementSupported: false,
+    },
+    {
+      name: "unknown runtimes support no placement",
+      runtimeId: "missing-harness",
+      executionMode: undefined,
+      devicePlacementSupported: false,
+    },
+  ] as const)("$name", ({ runtimeId, executionMode, devicePlacementSupported, ...declaration }) => {
+    if ("cloudPlacement" in declaration) {
+      const harness: AgentHarness = {
+        id: runtimeId,
+        label: runtimeId,
+        cloudPlacement: declaration.cloudPlacement,
+        supports: () => ({ supported: true }),
+        async runAttempt() {
+          throw new Error("not used");
+        },
+      };
+      registerAgentHarness(harness);
+    }
+
+    expect(resolveWorkerPlacementExecutionMode(runtimeId)).toBe(executionMode);
+    expect(resolveWorkerPlacementCapabilities(runtimeId)).toEqual({
+      ...(executionMode ? { executionMode } : {}),
+      ...("devicePlacement" in declaration ? { devicePlacement: declaration.devicePlacement } : {}),
+    });
+    expect(resolveWorkerPlacementCapabilities(runtimeId).devicePlacement !== undefined).toBe(
+      devicePlacementSupported,
+    );
+    expect(projectWorkerPlacementAgentRuntime({ id: runtimeId, source: "model" })).toEqual({
+      id: runtimeId,
+      cloudPlacementSupported: executionMode !== undefined,
+      ...(executionMode ? { cloudPlacementExecutionMode: executionMode } : {}),
+      ...("devicePlacement" in declaration ? { devicePlacement: declaration.devicePlacement } : {}),
+      devicePlacementSupported,
+      source: "model",
+    });
+  });
+
+  it("fails closed when a harness requires more than the bounded command count", () => {
+    registerAgentHarness({
+      id: "oversized-harness",
+      label: "oversized-harness",
+      cloudPlacement: {
+        mode: "remote-exec",
+        devicePlacement: {
+          requiredNodeCommands: Array.from({ length: 33 }, (_, index) => `runtime.${index}.v1`),
+          consumesWorkerSlot: false,
+        },
+      },
+      supports: () => ({ supported: true }),
+      async runAttempt() {
+        throw new Error("not used");
+      },
+    });
+
+    expect(resolveWorkerPlacementCapabilities("oversized-harness").devicePlacement).toBeUndefined();
+    expect(
+      projectWorkerPlacementAgentRuntime({ id: "oversized-harness", source: "model" }),
+    ).toEqual({
+      id: "oversized-harness",
+      cloudPlacementSupported: true,
+      cloudPlacementExecutionMode: "remote-exec",
+      devicePlacementSupported: false,
+      source: "model",
+    });
+  });
+});
diff --git a/src/gateway/worker-environments/placement-session-runtime.ts b/src/gateway/worker-environments/placement-session-runtime.ts
index 4c281b55b768..abd289a0b2d4 100644
--- a/src/gateway/worker-environments/placement-session-runtime.ts
+++ b/src/gateway/worker-environments/placement-session-runtime.ts
@@ -34,14 +34,42 @@ export function resolveWorkerPlacementSessionRuntime(params: {
 export function resolveWorkerPlacementExecutionMode(
   runtime: string,
 ): WorkerPlacementExecutionMode | undefined {
+  return resolveWorkerPlacementCapabilities(runtime).executionMode;
+}
+
+export function resolveWorkerPlacementCapabilities(runtime: string): {
+  executionMode?: WorkerPlacementExecutionMode;
+  devicePlacement?: NonNullable<GatewayAgentRuntime["devicePlacement"]>;
+} {
   const runtimeId = runtime.trim();
   if (runtimeId === OPENCLAW_AGENT_RUNTIME_ID) {
-    return "worker-turn";
+    return {
+      executionMode: "worker-turn",
+      devicePlacement: { requiredNodeCommands: [], consumesWorkerSlot: true },
+    };
   }
-  const harness = getRegisteredAgentHarness(runtimeId)?.harness as
-    | { cloudPlacement?: { mode: "remote-exec" } }
-    | undefined;
-  return harness?.cloudPlacement?.mode;
+  const placement = getRegisteredAgentHarness(runtimeId)?.harness.cloudPlacement;
+  if (!placement) {
+    return {};
+  }
+  const requirement = placement.devicePlacement;
+  if (!requirement) {
+    return { executionMode: placement.mode };
+  }
+  const requiredNodeCommands = [...new Set(requirement.requiredNodeCommands)].toSorted();
+  // Dropping an oversized or malformed required command would silently grant incomplete authority.
+  if (
+    requiredNodeCommands.length > 32 ||
+    requiredNodeCommands.some(
+      (command) => command.length === 0 || command.length > 128 || command.trim() !== command,
+    )
+  ) {
+    return { executionMode: placement.mode };
+  }
+  return {
+    executionMode: placement.mode,
+    devicePlacement: { requiredNodeCommands, consumesWorkerSlot: requirement.consumesWorkerSlot },
+  };
 }
 
 export function projectWorkerPlacementAgentRuntime(
@@ -49,15 +77,17 @@ export function projectWorkerPlacementAgentRuntime(
 ): GatewayAgentRuntime & {
   cloudPlacementSupported: boolean;
   cloudPlacementExecutionMode?: WorkerPlacementExecutionMode;
+  devicePlacement?: NonNullable<GatewayAgentRuntime["devicePlacement"]>;
   devicePlacementSupported: boolean;
 } {
   const { source, ...identity } = runtime;
-  const executionMode = resolveWorkerPlacementExecutionMode(runtime.id);
+  const { executionMode, devicePlacement } = resolveWorkerPlacementCapabilities(runtime.id);
   return {
     ...identity,
     cloudPlacementSupported: executionMode !== undefined,
     ...(executionMode ? { cloudPlacementExecutionMode: executionMode } : {}),
-    devicePlacementSupported: executionMode === "worker-turn",
+    ...(devicePlacement ? { devicePlacement } : {}),
+    devicePlacementSupported: devicePlacement !== undefined,
     source,
   };
 }
diff --git a/src/gateway/worker-environments/placement-store-terminal.test.ts b/src/gateway/worker-environments/placement-store-terminal.test.ts
index 39ebc466958c..6447850317d7 100644
--- a/src/gateway/worker-environments/placement-store-terminal.test.ts
+++ b/src/gateway/worker-environments/placement-store-terminal.test.ts
@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -7,7 +8,11 @@ import {
   openOpenClawStateDatabase,
   type OpenClawStateDatabase,
 } from "../../state/openclaw-state-db.js";
-import type { WorkerSessionPlacementIdentity, WorkerSessionTurnClaim } from "./placement-record.js";
+import {
+  placementTurnOwner,
+  type WorkerSessionPlacementIdentity,
+  type WorkerSessionTurnClaim,
+} from "./placement-record.js";
 import {
   createWorkerSessionPlacementStore,
   type WorkerSessionPlacementStore,
@@ -41,8 +46,9 @@ describe("worker placement terminal persistence", () => {
   function advanceToActive(
     identity: WorkerSessionPlacementIdentity = SESSION,
     environmentId = `environment-${identity.sessionId}`,
+    executionMode: "worker-turn" | "remote-exec" = "worker-turn",
   ) {
-    let placement = store.startDispatch(identity);
+    let placement = store.startDispatch({ ...identity, executionMode });
     placement = store.transition({
       sessionId: identity.sessionId,
       from: "requested",
@@ -87,11 +93,7 @@ describe("worker placement terminal persistence", () => {
     }
     const claim = store.claimTurn({
       ...identity,
-      owner: {
-        kind: "worker",
-        environmentId: active.environmentId,
-        ownerEpoch: active.activeOwnerEpoch,
-      },
+      owner: placementTurnOwner(active),
       claimId: `claim-${identity.sessionId}`,
       runId: `run-${identity.sessionId}`,
     });
@@ -194,6 +196,104 @@ describe("worker placement terminal persistence", () => {
     expect(reopened?.terminalReason).toBe(failed.terminalReason);
   });
 
+  it("atomically abandons an offline remote-exec result while preserving its exact active owner", () => {
+    advanceToActive(SESSION, "paired-device-environment", "remote-exec");
+    const { active, claim } = pendingResult();
+    const closedClaims: WorkerSessionTurnClaim[] = [];
+    const unregister = store.registerTurnClaimClosedHandler((closedClaim) => {
+      closedClaims.push(closedClaim);
+    });
+
+    const preserved = store.cancelWorkspaceResultAndReleaseTurn(claim, {
+      reason: "node-disconnect",
+    });
+
+    expect(preserved).toMatchObject({
+      state: "active",
+      environmentId: active.environmentId,
+      activeOwnerEpoch: active.activeOwnerEpoch,
+      generation: active.generation,
+      workspaceBaseManifestRef: active.workspaceBaseManifestRef,
+      turnClaim: null,
+      terminalReason: null,
+    });
+    expect(store.listPendingWorkspaceResults()).toEqual([]);
+    expect(closedClaims).toEqual([claim]);
+
+    const fresh = store.claimTurn({
+      ...SESSION,
+      owner: {
+        kind: "local",
+        environmentId: active.environmentId,
+        ownerEpoch: active.activeOwnerEpoch,
+      },
+      claimId: "fresh-paired-device-claim",
+      runId: "fresh-paired-device-run",
+    });
+    expect(fresh.claimId).not.toBe(claim.claimId);
+    expect(fresh.placementGeneration).toBe(active.generation);
+    unregister();
+  });
+
+  it.each([
+    "worker-owned",
+    "accepted",
+    "staged",
+    "journaled",
+    "stale-claim",
+    "other-gateway",
+  ] as const)("does not abandon a %s workspace result after node transport loss", (resultState) => {
+    const executionMode = resultState === "worker-owned" ? "worker-turn" : "remote-exec";
+    advanceToActive(SESSION, "paired-device-environment", executionMode);
+    const { active, claim } = pendingResult();
+    if (resultState === "accepted") {
+      store.acceptWorkspaceResult(claim);
+    } else if (resultState === "staged") {
+      store.recordStagedWorkspaceResult(claim, "refs/openclaw/worker-results/preserved-result");
+    } else if (resultState === "journaled") {
+      const basePack = Buffer.from("pending remote workspace snapshot");
+      store.beginWorkspaceReconciliation(
+        {
+          sessionId: active.sessionId,
+          environmentId: active.environmentId,
+          ownerEpoch: active.activeOwnerEpoch,
+          placementGeneration: active.generation,
+        },
+        {
+          version: 1,
+          temporaryNonce: "a".repeat(32),
+          baseManifestRef: active.workspaceBaseManifestRef,
+          currentManifestRef: `sha256:${"c".repeat(64)}`,
+          baseEntries: [],
+          appliedEntries: [],
+          baseTree: "f".repeat(40),
+          basePackSha256: createHash("sha256").update(basePack).digest("hex"),
+          basePack,
+        },
+      );
+    }
+
+    const cancellationStore =
+      resultState === "other-gateway"
+        ? createWorkerSessionPlacementStore({ database, now: () => nowMs })
+        : store;
+    const cancellationClaim =
+      resultState === "stale-claim" ? { ...claim, runId: "replacement-run" } : claim;
+    expect(() =>
+      cancellationStore.cancelWorkspaceResultAndReleaseTurn(cancellationClaim, {
+        reason: "node-disconnect",
+      }),
+    ).toThrow("workspace result owner changed before cancellation");
+    expect(store.get(active.sessionId)).toMatchObject({
+      state: "active",
+      generation: active.generation,
+      turnClaim: { claimId: claim.claimId },
+    });
+    expect(store.listPendingWorkspaceResults()).toMatchObject([
+      { sessionId: active.sessionId, claimId: claim.claimId },
+    ]);
+  });
+
   it("does not fail a pending result while its session operation is running", () => {
     advanceToActive();
     const { claim, pending } = pendingResult();
diff --git a/src/gateway/worker-environments/placement-store.ts b/src/gateway/worker-environments/placement-store.ts
index 2d2176e66c84..2b06aed32e74 100644
--- a/src/gateway/worker-environments/placement-store.ts
+++ b/src/gateway/worker-environments/placement-store.ts
@@ -15,6 +15,7 @@ import {
   normalizeEpoch,
   normalizeWorkerPlacementExecutionMode,
   normalizeIdentity,
+  placementTurnOwner,
   projectWorkerSessionTurnClaim,
   required,
   resolvePlacementTurnEnvironment,
@@ -350,6 +351,7 @@ export function createWorkerSessionPlacementStore(
       environmentId: string;
       ownerEpoch: number;
       expectedGeneration: number;
+      forceLocalClaim?: true;
     }): WorkerSessionPlacementRecord {
       const sessionId = required(input.sessionId, "session id");
       const environmentId = required(input.environmentId, "environment id");
@@ -371,15 +373,18 @@ export function createWorkerSessionPlacementStore(
         }
         // Clear the last claim in the same CAS that opens post-worker
         // reconciliation. Pending results block this authority fence.
-        const releasedClaim = current.turnClaim !== null;
-        if (current.turnClaim) {
+        const claim = current.turnClaim;
+        if (claim?.owner === "local" && input.forceLocalClaim !== true) {
+          throw new Error(`Cannot reconcile session ${sessionId} while its local turn is active`);
+        }
+        if (claim) {
           assertNoRunningWorkerSessionToolOperations(db, {
             sessionId,
-            claimId: current.turnClaim.claimId,
+            claimId: claim.claimId,
           });
           clearWorkerTurnToolState(db, {
             sessionId,
-            claimId: current.turnClaim.claimId,
+            claimId: claim.claimId,
           });
         }
         const values = transitionValues(current, "reconciling", {}, now());
@@ -391,13 +396,17 @@ export function createWorkerSessionPlacementStore(
           .where("transition_generation", "=", current.generation)
           .where("environment_id", "=", environmentId)
           .where("active_owner_epoch", "=", ownerEpoch);
-        const guardedUpdate = current.turnClaim
+        const guardedUpdate = claim
           ? update
-              .where("turn_claim_owner", "=", "worker")
-              .where("turn_claim_id", "=", current.turnClaim.claimId)
-              .where("turn_claim_run_id", "=", current.turnClaim.runId)
-              .where("turn_claim_generation", "=", current.turnClaim.generation)
-              .where("turn_claim_owner_epoch", "=", current.turnClaim.ownerEpoch)
+              .where("turn_claim_owner", "=", claim.owner)
+              .where("turn_claim_id", "=", claim.claimId)
+              .where("turn_claim_run_id", "=", claim.runId)
+              .where("turn_claim_generation", "=", claim.generation)
+              .where(
+                "turn_claim_owner_epoch",
+                claim.owner === "worker" ? "=" : "is",
+                claim.ownerEpoch,
+              )
           : update.where("turn_claim_owner", "is", null);
         const result = executeSqliteQuerySync(db, guardedUpdate);
         if (result.numAffectedRows !== 1n) {
@@ -405,7 +414,15 @@ export function createWorkerSessionPlacementStore(
         }
         return {
           record: getRequired(db, sessionId),
-          releasedClaim: releasedClaim ? projectWorkerSessionTurnClaim(current) : undefined,
+          releasedClaim: claim
+            ? {
+                sessionId,
+                claimId: claim.claimId,
+                runId: claim.runId,
+                placementGeneration: claim.generation,
+                owner: placementTurnOwner(current),
+              }
+            : undefined,
         };
       });
       if (outcome.releasedClaim) {
diff --git a/src/gateway/worker-environments/placement-store.turn-claim-closure.test.ts b/src/gateway/worker-environments/placement-store.turn-claim-closure.test.ts
index a30c6dc225f0..15d77a78b773 100644
--- a/src/gateway/worker-environments/placement-store.turn-claim-closure.test.ts
+++ b/src/gateway/worker-environments/placement-store.turn-claim-closure.test.ts
@@ -13,7 +13,7 @@ import {
   openOpenClawStateDatabase,
   type OpenClawStateDatabase,
 } from "../../state/openclaw-state-db.js";
-import type { WorkerSessionPlacementIdentity } from "./placement-record.js";
+import { placementTurnOwner, type WorkerSessionPlacementIdentity } from "./placement-record.js";
 import {
   createWorkerSessionPlacementStore,
   type WorkerSessionPlacementStore,
@@ -44,8 +44,8 @@ afterEach(async () => {
   await fs.rm(root, { recursive: true, force: true });
 });
 
-function advanceToActive() {
-  let placement = store.startDispatch(SESSION);
+function advanceToActive(executionMode: "worker-turn" | "remote-exec" = "worker-turn") {
+  let placement = store.startDispatch({ ...SESSION, executionMode });
   placement = store.transition({
     sessionId: SESSION.sessionId,
     from: "requested",
@@ -124,6 +124,67 @@ it("emits exact worker claim closure after release and owner fencing", () => {
   unregister();
 });
 
+it.each([
+  { ownerKind: "worker", executionMode: "worker-turn" },
+  { ownerKind: "local", executionMode: "remote-exec" },
+] as const)("fences the exact $ownerKind claim when reconciliation starts", (scenario) => {
+  const closed = vi.fn();
+  const unregister = store.registerTurnClaimClosedHandler(closed);
+  const active = advanceToActive(scenario.executionMode);
+  const claim = store.claimTurn({
+    ...SESSION,
+    owner: placementTurnOwner(active),
+    claimId: `claim-reconcile-${scenario.ownerKind}`,
+    runId: `run-reconcile-${scenario.ownerKind}`,
+  });
+  const draining = store.startDrain({
+    sessionId: active.sessionId,
+    environmentId: active.environmentId,
+    ownerEpoch: active.activeOwnerEpoch,
+    expectedGeneration: active.generation,
+  });
+  const reconcileInput = {
+    sessionId: active.sessionId,
+    environmentId: active.environmentId,
+    ownerEpoch: active.activeOwnerEpoch,
+    expectedGeneration: draining.generation,
+  };
+
+  expect(() =>
+    store.startReconcile({ ...reconcileInput, ownerEpoch: active.activeOwnerEpoch + 1 }),
+  ).toThrow("Cannot reconcile stale worker placement");
+  expect(store.get(active.sessionId)).toMatchObject({
+    state: "draining",
+    turnClaim: { claimId: claim.claimId, owner: scenario.ownerKind },
+  });
+  expect(closed).not.toHaveBeenCalled();
+
+  const authorizedReconcileInput =
+    scenario.ownerKind === "local"
+      ? { ...reconcileInput, forceLocalClaim: true as const }
+      : reconcileInput;
+  if (scenario.ownerKind === "local") {
+    const preserved = store.get(active.sessionId);
+    expect(() => store.startReconcile(reconcileInput)).toThrow("local turn is active");
+    expect(store.get(active.sessionId)).toEqual(preserved);
+    expect(store.validateTurnClaim(claim)).toBe(true);
+    expect(closed).not.toHaveBeenCalled();
+  }
+
+  expect(store.startReconcile(authorizedReconcileInput)).toMatchObject({
+    state: "reconciling",
+    turnClaim: null,
+  });
+  expect(store.validateTurnClaim(claim)).toBe(false);
+  expect(closed).toHaveBeenCalledExactlyOnceWith(claim);
+  expect(() => store.startReconcile(authorizedReconcileInput)).toThrow(
+    "Cannot reconcile stale worker placement",
+  );
+  expect(() => store.releaseTurn(claim)).toThrow("turn claim changed before release");
+  expect(closed).toHaveBeenCalledOnce();
+  unregister();
+});
+
 it("rejects retained worker lineage capabilities after either owner closes", async () => {
   const active = advanceToActive();
   const owner = {
diff --git a/src/gateway/worker-environments/placement-turn-claims.ts b/src/gateway/worker-environments/placement-turn-claims.ts
index 204b5b5f8fe0..200beaa7f767 100644
--- a/src/gateway/worker-environments/placement-turn-claims.ts
+++ b/src/gateway/worker-environments/placement-turn-claims.ts
@@ -250,15 +250,16 @@ export function createPlacementTurnClaimOps(runtime: PlacementStoreRuntime) {
 
     cancelWorkspaceResultAndReleaseTurn(
       claim: WorkerSessionTurnClaim,
+      options?: { reason: "node-disconnect" },
     ): WorkerSessionPlacementRecord {
       const sessionId = required(claim.sessionId, "session id");
       const claimId = required(claim.claimId, "turn claim id");
       const runId = required(claim.runId, "turn claim run id");
-      if (claimId !== runId || !claimId.startsWith("reclaim-")) {
+      const nodeDisconnect = options?.reason === "node-disconnect";
+      if (!nodeDisconnect && (claimId !== runId || !claimId.startsWith("reclaim-"))) {
         throw new Error(`Session ${sessionId} workspace result is not owned by reclaim`);
       }
-      // A failed stop must not expose a claim without its recovery fence (or vice
-      // versa), because either half-state permanently blocks the next reclaim.
+      // Claim and recovery fence disappear together; either surviving half blocks the next attempt.
       const released = write((db) => {
         const current = getRequired(db, sessionId);
         const environment = resolvePlacementTurnEnvironment(current, claim);
@@ -277,7 +278,21 @@ export function createPlacementTurnClaimOps(runtime: PlacementStoreRuntime) {
           pending.placement_generation !== claim.placementGeneration ||
           pending.claim_id !== claimId ||
           pending.run_id !== runId ||
-          pending.workspace_accepted_at_ms !== null
+          pending.workspace_accepted_at_ms !== null ||
+          (nodeDisconnect &&
+            (current.state !== "active" ||
+              current.executionMode !== "remote-exec" ||
+              claim.owner.kind !== "local" ||
+              pending.gateway_instance_id !== instanceId ||
+              pending.recovery_requested_at_ms !== null ||
+              pending.staged_result_ref !== null ||
+              executeSqliteQuerySync(
+                db,
+                workspaceJournalQuery(db)
+                  .selectFrom("worker_workspace_reconciliations")
+                  .select("session_id")
+                  .where("session_id", "=", sessionId),
+              ).rows.length > 0))
         ) {
           throw new Error(
             `Session ${sessionId} workspace result owner changed before cancellation`,
diff --git a/src/gateway/worker-environments/provider-lifecycle.ts b/src/gateway/worker-environments/provider-lifecycle.ts
index b8d32c3158c9..940126b96797 100644
--- a/src/gateway/worker-environments/provider-lifecycle.ts
+++ b/src/gateway/worker-environments/provider-lifecycle.ts
@@ -61,7 +61,7 @@ export function createWorkerProviderLifecycle(options: WorkerProviderLifecycleOp
 
   const identityResolverFor = (
     record: WorkerEnvironmentRecord,
-    provider: WorkerProvider,
+    provider: WorkerProvider<"internal">,
     leaseId: string,
   ) => {
     const profile = requireWorkerProfile(record.profileSnapshot.settings);
@@ -76,7 +76,7 @@ export function createWorkerProviderLifecycle(options: WorkerProviderLifecycleOp
     };
   };
 
-  const providerFor = (providerId: string): WorkerProvider => {
+  const providerFor = (providerId: string): WorkerProvider<"internal"> => {
     const provider = options.resolveProvider(providerId);
     if (provider) {
       return provider;
@@ -126,7 +126,7 @@ export function createWorkerProviderLifecycle(options: WorkerProviderLifecycleOp
   const failBootstrap = async (
     record: WorkerEnvironmentRecord,
     leaseId: string,
-    provider: WorkerProvider,
+    provider: WorkerProvider<"internal">,
     error: unknown,
     failureCode: "bootstrap_failure" | "invalid_profile" = "bootstrap_failure",
     leasePatch?: TransitionPatch,
@@ -199,7 +199,7 @@ export function createWorkerProviderLifecycle(options: WorkerProviderLifecycleOp
 
   const finishBootstrap = async (
     record: WorkerEnvironmentRecord,
-    provider: WorkerProvider,
+    provider: WorkerProvider<"internal">,
     installation: WorkerInstallationArtifact,
   ) => {
     if (record.state !== "bootstrapping" || !record.leaseId || !record.sshEndpoint) {
@@ -229,7 +229,7 @@ export function createWorkerProviderLifecycle(options: WorkerProviderLifecycleOp
 
   const finishProvision = async (
     record: WorkerEnvironmentRecord,
-    provider: WorkerProvider,
+    provider: WorkerProvider<"internal">,
     preparedInstallation?: WorkerInstallationArtifact,
   ) => {
     let lease: WorkerLease;
@@ -375,7 +375,10 @@ export function createWorkerProviderLifecycle(options: WorkerProviderLifecycleOp
     throw serviceError("invalid_state", `Cannot destroy worker in state: ${record.state}`);
   };
 
-  const finishDestroy = async (r: WorkerEnvironmentRecord, provider?: WorkerProvider) => {
+  const finishDestroy = async (
+    r: WorkerEnvironmentRecord,
+    provider?: WorkerProvider<"internal">,
+  ) => {
     if (!r.leaseId) {
       throw serviceError("invalid_state", "Worker environment has no lease");
     }
@@ -415,7 +418,7 @@ export function createWorkerProviderLifecycle(options: WorkerProviderLifecycleOp
         // Provider inspection and the state-specific path below retain their existing retry policy.
       }
     }
-    let provider: WorkerProvider;
+    let provider: WorkerProvider<"internal">;
     try {
       provider = providerFor(record.providerId);
     } catch (error) {
@@ -624,7 +627,7 @@ export function createWorkerProviderLifecycle(options: WorkerProviderLifecycleOp
         }
         return existing;
       }
-      let provider: WorkerProvider;
+      let provider: WorkerProvider<"internal">;
       let providerId: string;
       let profileSnapshot: WorkerProfile;
       if (inherited) {
diff --git a/src/gateway/worker-environments/provider-lifecycle.types.ts b/src/gateway/worker-environments/provider-lifecycle.types.ts
index 44354104dea9..276d3eb933a3 100644
--- a/src/gateway/worker-environments/provider-lifecycle.types.ts
+++ b/src/gateway/worker-environments/provider-lifecycle.types.ts
@@ -21,7 +21,7 @@ import type { WorkerTunnelManager } from "./tunnel.js";
 export type WorkerProviderLifecycleInputOptions = {
   store: WorkerEnvironmentStore;
   getConfig: () => OpenClawConfig;
-  resolveProvider: (providerId: string) => WorkerProvider | undefined;
+  resolveProvider: (providerId: string) => WorkerProvider<"internal"> | undefined;
   prepareInstallation: (
     install: WorkerInstallationArtifact["install"],
   ) => Promise<WorkerInstallationArtifact>;
@@ -33,7 +33,7 @@ export type WorkerProviderLifecycleInputOptions = {
     signal: AbortSignal;
   }) => Promise<WorkerAdmissionHandshake>;
   resolveSshIdentity?: (params: {
-    provider: WorkerProvider;
+    provider: WorkerProvider<"internal">;
     leaseId: string;
     profile: WorkerProfile;
     keyRef: SecretRef;
diff --git a/src/gateway/worker-environments/provider-node-provisioning.ts b/src/gateway/worker-environments/provider-node-provisioning.ts
index 5c4e604eac18..46773bff050c 100644
--- a/src/gateway/worker-environments/provider-node-provisioning.ts
+++ b/src/gateway/worker-environments/provider-node-provisioning.ts
@@ -20,7 +20,7 @@ type WorkerNodeProvisioningOptions = {
   destroyProviderLease: (
     record: WorkerEnvironmentRecord,
     leaseId: string,
-    provider: WorkerProvider,
+    provider: WorkerProvider<"internal">,
   ) => Promise<void>;
   finishProvenDestroy: (record: WorkerEnvironmentRecord) => Promise<WorkerEnvironmentRecord>;
   saveError: (record: WorkerEnvironmentRecord, error: unknown) => WorkerEnvironmentRecord;
@@ -31,7 +31,7 @@ export function createWorkerNodeProvisioning(options: WorkerNodeProvisioningOpti
   const fail = async (
     record: WorkerEnvironmentRecord,
     lease: NodeLease,
-    provider: WorkerProvider,
+    provider: WorkerProvider<"internal">,
     error: unknown,
   ): Promise<never> => {
     const detail = boundedError(error);
@@ -70,7 +70,7 @@ export function createWorkerNodeProvisioning(options: WorkerNodeProvisioningOpti
   return async (
     record: WorkerEnvironmentRecord,
     lease: NodeLease,
-    provider: WorkerProvider,
+    provider: WorkerProvider<"internal">,
     patch: { leaseId: string; sharedHost: boolean; desktop: WorkerLease["desktop"] | null },
   ): Promise<WorkerEnvironmentRecord> => {
     let nodeBuild: WorkerAdmissionHandshake;
diff --git a/src/gateway/worker-environments/provider-persisted-lease.ts b/src/gateway/worker-environments/provider-persisted-lease.ts
index 9c8c35a4b179..ea158302d137 100644
--- a/src/gateway/worker-environments/provider-persisted-lease.ts
+++ b/src/gateway/worker-environments/provider-persisted-lease.ts
@@ -20,11 +20,11 @@ export function requestStaleWorkerDestroy(
 
 export async function retireMismatchedWorkerLease(
   record: WorkerEnvironmentRecord,
-  provider: WorkerProvider,
+  provider: WorkerProvider<"internal">,
   store: WorkerEnvironmentStore,
   finishDestroy: (
     record: WorkerEnvironmentRecord,
-    provider: WorkerProvider,
+    provider: WorkerProvider<"internal">,
   ) => Promise<WorkerEnvironmentRecord>,
 ): Promise<boolean> {
   const transportMode = record.nodeDeviceId
diff --git a/src/gateway/worker-environments/reclaimed-placement-redispatch.test.ts b/src/gateway/worker-environments/reclaimed-placement-redispatch.test.ts
index 73f4370e3457..117c30e7f5c3 100644
--- a/src/gateway/worker-environments/reclaimed-placement-redispatch.test.ts
+++ b/src/gateway/worker-environments/reclaimed-placement-redispatch.test.ts
@@ -10,6 +10,7 @@ const placement = {
   sessionKey: "agent:main:cloud-session",
   agentId: "main",
   environmentId: "worker:previous",
+  executionMode: "worker-turn",
 } as ReclaimedWorkerPlacement;
 
 describe("createReclaimedPlacementRedispatch", () => {
@@ -37,6 +38,7 @@ describe("createReclaimedPlacementRedispatch", () => {
       sessionKey: placement.sessionKey,
       agentId: placement.agentId,
       profileId: "development",
+      executionMode: "worker-turn",
       inheritedProfile: {
         providerId: "fake",
         profileSnapshot: { machineClass: "large", settings: { region: "parent" } },
@@ -44,6 +46,56 @@ describe("createReclaimedPlacementRedispatch", () => {
     });
   });
 
+  it("carries the exact paired node and owner-resolved requirement through redispatch", async () => {
+    const requirement = { requiredNodeCommands: [], consumesWorkerSlot: true };
+    const dispatch = vi.fn(async () => ({ state: "active" }) as never);
+    const resolveDevicePlacementRequirement = vi.fn(async () => requirement);
+    const redispatch = createReclaimedPlacementRedispatch({
+      environments: {
+        get: () =>
+          ({
+            profileId: "device:paired-node",
+            providerId: "device",
+            nodeDeviceId: "paired-node",
+            profileSnapshot: { install: "bundle", settings: { device: "paired-node" } },
+          }) as never,
+      },
+      dispatch,
+      resolveDevicePlacementRequirement,
+    });
+
+    await redispatch(placement);
+
+    expect(resolveDevicePlacementRequirement).toHaveBeenCalledWith({
+      sessionId: placement.sessionId,
+      sessionKey: placement.sessionKey,
+      agentId: placement.agentId,
+      executionMode: "worker-turn",
+    });
+    expect(dispatch).toHaveBeenCalledWith(
+      expect.objectContaining({ deviceId: "paired-node", devicePlacement: requirement }),
+    );
+  });
+
+  it("rejects paired-device redispatch without its runtime requirement owner", async () => {
+    const dispatch = vi.fn();
+    const redispatch = createReclaimedPlacementRedispatch({
+      environments: {
+        get: () =>
+          ({
+            profileId: "device:paired-node",
+            providerId: "device",
+            nodeDeviceId: "paired-node",
+            profileSnapshot: { install: "bundle", settings: { device: "paired-node" } },
+          }) as never,
+      },
+      dispatch,
+    });
+
+    await expect(redispatch(placement)).rejects.toThrow("authoritative runtime requirement");
+    expect(dispatch).not.toHaveBeenCalled();
+  });
+
   it("fails closed when the prior environment record is unavailable", async () => {
     const redispatch = createReclaimedPlacementRedispatch({
       environments: { get: () => undefined },
diff --git a/src/gateway/worker-environments/reclaimed-placement-redispatch.ts b/src/gateway/worker-environments/reclaimed-placement-redispatch.ts
index f6279f65ca4e..516b4023f992 100644
--- a/src/gateway/worker-environments/reclaimed-placement-redispatch.ts
+++ b/src/gateway/worker-environments/reclaimed-placement-redispatch.ts
@@ -1,3 +1,5 @@
+import { DEVICE_WORKER_PROVIDER_ID } from "./device-provider-identity.js";
+import type { WorkerDevicePlacementRequirementResolver } from "./placement-dispatch-startup.js";
 import type { WorkerPlacementDispatchService } from "./placement-dispatch.js";
 import type { WorkerSessionPlacementRecord } from "./placement-record.js";
 import type { WorkerEnvironmentService } from "./service.js";
@@ -7,6 +9,7 @@ type ReclaimedWorkerPlacement = Extract<WorkerSessionPlacementRecord, { state: "
 export function createReclaimedPlacementRedispatch(params: {
   environments: Pick<WorkerEnvironmentService, "get">;
   dispatch: WorkerPlacementDispatchService["dispatch"];
+  resolveDevicePlacementRequirement?: WorkerDevicePlacementRequirementResolver;
 }) {
   return async (placement: ReclaimedWorkerPlacement) => {
     const previousEnvironment = params.environments.get(placement.environmentId);
@@ -15,12 +18,31 @@ export function createReclaimedPlacementRedispatch(params: {
         `Reclaimed worker placement has no environment record: ${placement.environmentId}`,
       );
     }
+    let devicePlacement: Awaited<ReturnType<WorkerDevicePlacementRequirementResolver>> | undefined;
+    if (
+      previousEnvironment.providerId === DEVICE_WORKER_PROVIDER_ID &&
+      previousEnvironment.nodeDeviceId
+    ) {
+      if (!params.resolveDevicePlacementRequirement) {
+        throw new Error("Paired-device redispatch has no authoritative runtime requirement");
+      }
+      devicePlacement = await params.resolveDevicePlacementRequirement({
+        sessionId: placement.sessionId,
+        sessionKey: placement.sessionKey,
+        agentId: placement.agentId,
+        executionMode: placement.executionMode,
+      });
+    }
     return await params.dispatch({
       sessionId: placement.sessionId,
       sessionKey: placement.sessionKey,
       agentId: placement.agentId,
       profileId: previousEnvironment.profileId,
       executionMode: placement.executionMode,
+      ...(previousEnvironment.providerId === DEVICE_WORKER_PROVIDER_ID &&
+      previousEnvironment.nodeDeviceId
+        ? { deviceId: previousEnvironment.nodeDeviceId, devicePlacement }
+        : {}),
       inheritedProfile: {
         providerId: previousEnvironment.providerId,
         profileSnapshot: previousEnvironment.profileSnapshot,
diff --git a/src/gateway/worker-environments/service-contract.ts b/src/gateway/worker-environments/service-contract.ts
index f79d871ef440..307676f76c67 100644
--- a/src/gateway/worker-environments/service-contract.ts
+++ b/src/gateway/worker-environments/service-contract.ts
@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import type { DevicePlacementRequirement } from "../../agents/harness/types.js";
 import type {
   WorkerDesktopApp,
   WorkerMachineOption,
@@ -93,6 +94,7 @@ export type WorkerPlacementDispatchRequest = {
   agentId: string;
   profileId: string;
   executionMode: WorkerPlacementExecutionMode;
+  devicePlacement?: DevicePlacementRequirement;
   idempotencyKey?: string;
   deviceId?: string;
   machineClass?: string;
@@ -104,7 +106,12 @@ export type WorkerPlacementDispatchRequest = {
 
 export type WorkerPlacementMoveDestination = Pick<
   WorkerPlacementDispatchRequest,
-  "profileId" | "executionMode" | "deviceId" | "machineClass" | "inheritedProfile"
+  | "profileId"
+  | "executionMode"
+  | "devicePlacement"
+  | "deviceId"
+  | "machineClass"
+  | "inheritedProfile"
 >;
 
 export type WorkerPlacementReclaimRequest = {
diff --git a/src/gateway/worker-environments/service-validation.ts b/src/gateway/worker-environments/service-validation.ts
index c8b7906cb836..cf1bf3a26497 100644
--- a/src/gateway/worker-environments/service-validation.ts
+++ b/src/gateway/worker-environments/service-validation.ts
@@ -87,7 +87,7 @@ export function requireWorkerLeaseStatus(value: unknown): WorkerLeaseStatus {
 }
 
 export function resolveWorkerTransportModeError(
-  provider: WorkerProvider,
+  provider: WorkerProvider<"internal">,
   transportMode: WorkerExecutionMode,
 ): WorkerProviderError | undefined {
   const modes = provider.supportedExecutionModes;
@@ -100,7 +100,7 @@ export function resolveWorkerTransportModeError(
 }
 
 export function resolveWorkerLeaseModeError(
-  provider: WorkerProvider,
+  provider: WorkerProvider<"internal">,
   lease: WorkerLease,
 ): WorkerProviderError | undefined {
   return resolveWorkerTransportModeError(provider, lease.node ? "worker-turn" : "remote-exec");
diff --git a/src/gateway/worker-environments/tunnel-contract.ts b/src/gateway/worker-environments/tunnel-contract.ts
index 11761af9d344..81f26e34034c 100644
--- a/src/gateway/worker-environments/tunnel-contract.ts
+++ b/src/gateway/worker-environments/tunnel-contract.ts
@@ -12,8 +12,8 @@ import type {
 export type { WorkerTunnelStatus };
 
 export class WorkerTunnelOwnerDisconnectedError extends Error {
-  constructor() {
-    super("Worker tunnel owner is no longer connected");
+  constructor(message = "Worker tunnel owner is no longer connected") {
+    super(message);
     this.name = "WorkerTunnelOwnerDisconnectedError";
   }
 }
diff --git a/src/gateway/worker-environments/worker-turn-launcher.test.ts b/src/gateway/worker-environments/worker-turn-launcher.test.ts
index 8fbaf21cae98..7babc7dc3c7a 100644
--- a/src/gateway/worker-environments/worker-turn-launcher.test.ts
+++ b/src/gateway/worker-environments/worker-turn-launcher.test.ts
@@ -13,7 +13,7 @@ import {
 import { createChatRunState } from "../server-chat-state.js";
 import { prepareSessionArchiveLifecycle } from "../server-methods/sessions-archive-lifecycle.js";
 import type { GatewayRequestContext } from "../server-methods/types.js";
-import type { WorkerTunnelHandle } from "./tunnel-contract.js";
+import { WorkerTunnelOwnerDisconnectedError, type WorkerTunnelHandle } from "./tunnel-contract.js";
 import {
   ENVIRONMENT_ID,
   MANIFEST_REF,
@@ -404,131 +404,380 @@ describe("worker turn launcher local placement", () => {
     },
   );
 
-  it("runs an active remote-exec placement locally and reconciles before releasing its claim", async () => {
-    seedActivePlacement("remote-exec");
-    const order: string[] = [];
-    const launchTurn = vi.fn();
-    const quiesceWorkspace = vi.fn(async () => {
-      order.push("quiesce");
-      return {
-        assertActive: vi.fn(async () => {}),
-        resume: vi.fn(async () => {
-          order.push("resume");
-        }),
-      };
-    });
-    const reconcileWorkspace = vi.fn(
-      async (request: Parameters<WorkerTunnelHandle["reconcileWorkspace"]>[0]) => {
-        order.push("reconcile");
-        request.journal.commit(MANIFEST_REF);
+  it.each([
+    { label: "SSH", nodeDeviceId: undefined },
+    { label: "paired-device", nodeDeviceId: "paired-node-1" },
+  ])(
+    "runs a $label remote-exec placement locally and reconciles without launching a worker child",
+    async ({ nodeDeviceId }) => {
+      seedActivePlacement("remote-exec");
+      const order: string[] = [];
+      const launchTurn = vi.fn();
+      const quiesceWorkspace = vi.fn(async () => {
+        order.push("quiesce");
         return {
-          manifestRef: MANIFEST_REF,
-          changed: false,
-          verifyStable: vi.fn(async () => {}),
-          verifyLocalStable: vi.fn(async () => {}),
+          assertActive: vi.fn(async () => {}),
+          resume: vi.fn(async () => {
+            order.push("resume");
+          }),
         };
-      },
-    );
-    const tunnel: WorkerTunnelHandle = {
-      environmentId: ENVIRONMENT_ID,
-      ownerEpoch: OWNER_EPOCH,
-      launchTurn,
-      runWorkspaceCommand: vi.fn(),
-      quiesceWorkspace,
-      syncWorkspace: vi.fn(),
-      reconcileWorkspace,
-      stop: vi.fn(async () => {}),
-    };
-    const environments: WorkerTurnEnvironmentService = {
-      ...unusedEnvironments(),
-      get: vi.fn(() => attachedEnvironment()),
-      startTunnel: vi.fn(async () => tunnel),
-    };
-    const provider = createWorkerSessionTurnPlacementProvider({ environments, placements });
-    const runLocal = vi.fn(async () => {
-      order.push("local");
-      return { payloads: [{ text: "local remote reply" }], meta: { durationMs: 1 } };
-    });
+      });
+      const reconcileWorkspace = vi.fn(
+        async (request: Parameters<WorkerTunnelHandle["reconcileWorkspace"]>[0]) => {
+          order.push("reconcile");
+          request.journal.commit(MANIFEST_REF);
+          return {
+            manifestRef: MANIFEST_REF,
+            changed: false,
+            verifyStable: vi.fn(async () => {}),
+            verifyLocalStable: vi.fn(async () => {}),
+          };
+        },
+      );
+      const tunnel: WorkerTunnelHandle = {
+        environmentId: ENVIRONMENT_ID,
+        ownerEpoch: OWNER_EPOCH,
+        launchTurn,
+        runWorkspaceCommand: vi.fn(),
+        quiesceWorkspace,
+        syncWorkspace: vi.fn(),
+        reconcileWorkspace,
+        stop: vi.fn(async () => {}),
+      };
+      const environments: WorkerTurnEnvironmentService = {
+        ...unusedEnvironments(),
+        get: vi.fn(() =>
+          nodeDeviceId
+            ? { ...attachedEnvironment(), providerId: "device", nodeDeviceId, sshEndpoint: null }
+            : attachedEnvironment(),
+        ),
+        startTunnel: vi.fn(async () => tunnel),
+      };
+      const provider = createWorkerSessionTurnPlacementProvider({ environments, placements });
+      const runLocal = vi.fn(async () => {
+        order.push("local");
+        return { payloads: [{ text: "local remote reply" }], meta: { durationMs: 1 } };
+      });
 
-    await provider.executeTurn(
-      {
-        sessionId: SESSION_ID,
-        sessionKey: SESSION_KEY,
-        agentId: "main",
-        runId: "run-remote-exec",
-      },
-      turn("run-remote-exec"),
-      runLocal,
-    );
-
-    expect(order).toEqual(["local", "quiesce", "reconcile", "resume"]);
-    expect(launchTurn).not.toHaveBeenCalled();
-    expect(environments.acquireTurnCredential).not.toHaveBeenCalled();
-    expect(placements.listPendingWorkspaceResults()).toEqual([]);
-    const placement = placements.get(SESSION_ID);
-    expect([placement?.state, placement?.turnClaim]).toEqual(["active", null]);
-  });
-
-  it("records a remote-exec reconciliation failure and releases its local claim", async () => {
-    seedActivePlacement("remote-exec");
-    const reconciliationError = new Error("workspace manifest memo exceeds its entry limit");
-    const tunnel: WorkerTunnelHandle = {
-      environmentId: ENVIRONMENT_ID,
-      ownerEpoch: OWNER_EPOCH,
-      launchTurn: vi.fn(),
-      runWorkspaceCommand: vi.fn(),
-      quiesceWorkspace: vi.fn(async () => ({
-        assertActive: vi.fn(async () => {}),
-        resume: vi.fn(async () => {}),
-      })),
-      syncWorkspace: vi.fn(),
-      reconcileWorkspace: vi.fn(async () => {
-        throw reconciliationError;
-      }),
-      stop: vi.fn(async () => {}),
-    };
-    const environments: WorkerTurnEnvironmentService = {
-      ...unusedEnvironments(),
-      get: vi.fn(() => attachedEnvironment()),
-      startTunnel: vi.fn(async () => tunnel),
-    };
-    const reconcileActivePlacement = vi.fn(async () => {
-      const placement = placements.get(SESSION_ID);
-      if (placement?.state !== "failed" || placement.turnClaim !== null) {
-        throw new Error("expected terminal placement before teardown recovery");
-      }
-      expect(placements.listPendingWorkspaceResults()).toEqual([]);
-    });
-    const provider = createWorkerSessionTurnPlacementProvider({
-      environments,
-      placements,
-      reconcileActivePlacement,
-    });
-
-    await expect(
-      provider.executeTurn(
+      await provider.executeTurn(
         {
           sessionId: SESSION_ID,
           sessionKey: SESSION_KEY,
           agentId: "main",
-          runId: "run-remote-exec-reconcile-failure",
+          runId: "run-remote-exec",
         },
-        turn("run-remote-exec-reconcile-failure"),
-        async () => ({ payloads: [{ text: "remote work completed" }], meta: { durationMs: 1 } }),
-      ),
-    ).rejects.toThrow(
-      "Cloud worker finished, but its workspace result could not be reconciled: workspace manifest memo exceeds its entry limit",
-    );
+        turn("run-remote-exec"),
+        runLocal,
+      );
 
-    expect(reconcileActivePlacement).toHaveBeenCalledWith(ENVIRONMENT_ID);
-    expect(placements.get(SESSION_ID)).toMatchObject({
-      state: "failed",
-      turnClaim: null,
-      terminalReason: expect.stringContaining("workspace manifest memo exceeds its entry limit"),
+      expect(order).toEqual(["local", "quiesce", "reconcile", "resume"]);
+      expect(launchTurn).not.toHaveBeenCalled();
+      expect(environments.acquireTurnCredential).not.toHaveBeenCalled();
+      expect(placements.listPendingWorkspaceResults()).toEqual([]);
+      const placement = placements.get(SESSION_ID);
+      expect([placement?.state, placement?.turnClaim]).toEqual(["active", null]);
+    },
+  );
+
+  it("resolves an exact paired-device sandbox without requiring an SSH identity resolver", async () => {
+    seedActivePlacement("remote-exec");
+    const environment = {
+      ...attachedEnvironment(),
+      providerId: "device",
+      nodeDeviceId: "paired-node-1",
+      sharedHost: true,
+      sshEndpoint: null,
+    };
+    const environments: WorkerTurnEnvironmentService = {
+      ...unusedEnvironments(),
+      get: vi.fn(() => environment),
+      resolveSshIdentity: undefined,
+    };
+    const provider = createWorkerSessionTurnPlacementProvider({ environments, placements });
+
+    await expect(
+      provider.resolveSandbox({
+        agentId: "main",
+        sessionId: SESSION_ID,
+        sessionKey: SESSION_KEY,
+        workspaceDir: "/caller/workspace",
+      }),
+    ).resolves.toMatchObject({
+      backendId: "node",
+      placementExecutionMode: "remote-exec",
+      placementNodeId: "paired-node-1",
+      containerWorkdir: "/worker/workspace",
     });
-    expect(placements.listPendingWorkspaceResults()).toEqual([]);
   });
 
+  it("rejects a remote-exec placement replaced while resolving its managed workspace", async () => {
+    seedActivePlacement("remote-exec");
+    const environment = attachedEnvironment();
+    const provider = createWorkerSessionTurnPlacementProvider({
+      environments: { ...unusedEnvironments(), get: vi.fn(() => environment) },
+      placements,
+      resolveWorkspacePath: async () => {
+        const placement = placements.get(SESSION_ID);
+        if (placement?.state !== "active") {
+          throw new Error("expected an active placement");
+        }
+        placements.startDrain({
+          sessionId: SESSION_ID,
+          environmentId: placement.environmentId,
+          ownerEpoch: placement.activeOwnerEpoch,
+          expectedGeneration: placement.generation,
+        });
+        return "/local/managed-worktree";
+      },
+    });
+
+    await expect(
+      provider.resolveSandbox({
+        agentId: "main",
+        sessionId: SESSION_ID,
+        sessionKey: SESSION_KEY,
+        workspaceDir: "/caller/workspace",
+      }),
+    ).rejects.toThrow("changed while preparing its managed workspace");
+  });
+
+  it("rejects a paired-node environment replaced after sandbox preparation", async () => {
+    seedActivePlacement("remote-exec");
+    const environment = {
+      ...attachedEnvironment(),
+      providerId: "device",
+      nodeDeviceId: "paired-node-1",
+      sshEndpoint: null,
+    };
+    const get = vi
+      .fn<WorkerTurnEnvironmentService["get"]>()
+      .mockReturnValueOnce(environment)
+      .mockReturnValueOnce(environment)
+      .mockReturnValueOnce({ ...environment, nodeDeviceId: "replacement-node" });
+    const provider = createWorkerSessionTurnPlacementProvider({
+      environments: { ...unusedEnvironments(), get },
+      placements,
+    });
+
+    await expect(
+      provider.resolveSandbox({
+        agentId: "main",
+        sessionId: SESSION_ID,
+        sessionKey: SESSION_KEY,
+        workspaceDir: "/caller/workspace",
+      }),
+    ).rejects.toThrow("environment changed while preparing its sandbox");
+  });
+
+  it.each([
+    {
+      scenario: "successful execution",
+      executionFailure: undefined,
+      expectedError:
+        "Cloud worker finished, but its workspace result could not be reconciled: workspace manifest memo exceeds its entry limit",
+      expectedTerminalReason: "workspace manifest memo exceeds its entry limit",
+    },
+    {
+      scenario: "failed execution",
+      executionFailure: "Codex paired execution device disconnected; start a fresh attempt",
+      expectedError: "Codex paired execution device disconnected; start a fresh attempt",
+      expectedTerminalReason: "Codex paired execution device disconnected; start a fresh attempt",
+    },
+  ])(
+    "records a remote-exec reconciliation failure after $scenario and releases its local claim",
+    async ({ executionFailure, expectedError, expectedTerminalReason }) => {
+      seedActivePlacement("remote-exec");
+      const reconciliationError = new Error("workspace manifest memo exceeds its entry limit");
+      const tunnel: WorkerTunnelHandle = {
+        environmentId: ENVIRONMENT_ID,
+        ownerEpoch: OWNER_EPOCH,
+        launchTurn: vi.fn(),
+        runWorkspaceCommand: vi.fn(),
+        quiesceWorkspace: vi.fn(async () => ({
+          assertActive: vi.fn(async () => {}),
+          resume: vi.fn(async () => {}),
+        })),
+        syncWorkspace: vi.fn(),
+        reconcileWorkspace: vi.fn(async () => {
+          throw reconciliationError;
+        }),
+        stop: vi.fn(async () => {}),
+      };
+      const environments: WorkerTurnEnvironmentService = {
+        ...unusedEnvironments(),
+        get: vi.fn(() => attachedEnvironment()),
+        startTunnel: vi.fn(async () => tunnel),
+      };
+      const reconcileActivePlacement = vi.fn(async () => {
+        const placement = placements.get(SESSION_ID);
+        if (placement?.state !== "failed" || placement.turnClaim !== null) {
+          throw new Error("expected terminal placement before teardown recovery");
+        }
+        expect(placements.listPendingWorkspaceResults()).toEqual([]);
+      });
+      const provider = createWorkerSessionTurnPlacementProvider({
+        environments,
+        placements,
+        reconcileActivePlacement,
+      });
+
+      await expect(
+        provider.executeTurn(
+          {
+            sessionId: SESSION_ID,
+            sessionKey: SESSION_KEY,
+            agentId: "main",
+            runId: "run-remote-exec-reconcile-failure",
+          },
+          turn("run-remote-exec-reconcile-failure"),
+          async () => {
+            if (executionFailure) {
+              throw new Error(executionFailure);
+            }
+            return { payloads: [{ text: "remote work completed" }], meta: { durationMs: 1 } };
+          },
+        ),
+      ).rejects.toMatchObject({
+        message: expectedError,
+        ...(executionFailure
+          ? {
+              cause: expect.objectContaining({
+                message: expect.stringContaining(reconciliationError.message),
+              }),
+            }
+          : {}),
+      });
+
+      expect(reconcileActivePlacement).toHaveBeenCalledWith(ENVIRONMENT_ID);
+      expect(placements.get(SESSION_ID)).toMatchObject({
+        state: "failed",
+        turnClaim: null,
+        terminalReason: expect.stringContaining(expectedTerminalReason),
+      });
+      expect(placements.listPendingWorkspaceResults()).toEqual([]);
+    },
+  );
+
+  it.each([
+    { label: "failed execution", executionFailed: true },
+    { label: "successful execution", executionFailed: false },
+  ])(
+    "preserves a disconnected paired-node placement after $label for a fresh attempt",
+    async ({ executionFailed }) => {
+      seedActivePlacement("remote-exec");
+      const original = placements.get(SESSION_ID);
+      if (original?.state !== "active") {
+        throw new Error("expected an active paired-device placement");
+      }
+      let connected = false;
+      const quiesceWorkspace = vi.fn(async () => {
+        if (!connected) {
+          throw new WorkerTunnelOwnerDisconnectedError(
+            "device worker node is not connected with the supervisor dialect",
+          );
+        }
+        return { assertActive: vi.fn(async () => {}), resume: vi.fn(async () => {}) };
+      });
+      const reconcileWorkspace = vi.fn(
+        async (request: Parameters<WorkerTunnelHandle["reconcileWorkspace"]>[0]) => {
+          request.journal.commit(MANIFEST_REF);
+          return {
+            manifestRef: MANIFEST_REF,
+            changed: false,
+            verifyStable: vi.fn(async () => {}),
+            verifyLocalStable: vi.fn(async () => {}),
+          };
+        },
+      );
+      const launchTurn = vi.fn();
+      const tunnel: WorkerTunnelHandle = {
+        environmentId: ENVIRONMENT_ID,
+        ownerEpoch: OWNER_EPOCH,
+        launchTurn,
+        runWorkspaceCommand: vi.fn(),
+        quiesceWorkspace,
+        syncWorkspace: vi.fn(),
+        reconcileWorkspace,
+        stop: vi.fn(async () => {}),
+      };
+      const environment = {
+        ...attachedEnvironment(),
+        providerId: "device",
+        nodeDeviceId: "paired-node-1",
+        sshEndpoint: null,
+      };
+      const environments: WorkerTurnEnvironmentService = {
+        ...unusedEnvironments(),
+        get: vi.fn(() => environment),
+        startTunnel: vi.fn(async () => tunnel),
+      };
+      const reconcileActivePlacement = vi.fn(async () => {});
+      const provider = createWorkerSessionTurnPlacementProvider({
+        environments,
+        placements,
+        reconcileActivePlacement,
+      });
+      const executionFailure = executionFailed
+        ? "Codex paired execution device disconnected; start a fresh attempt"
+        : undefined;
+
+      await expect(
+        provider.executeTurn(
+          {
+            sessionId: SESSION_ID,
+            sessionKey: SESSION_KEY,
+            agentId: "main",
+            runId: "run-paired-device-disconnected",
+          },
+          turn("run-paired-device-disconnected"),
+          async () => {
+            if (executionFailure) {
+              throw new Error(executionFailure);
+            }
+            return { payloads: [{ text: "remote work completed" }], meta: { durationMs: 1 } };
+          },
+        ),
+      ).rejects.toMatchObject({
+        message:
+          executionFailure ?? expect.stringContaining("workspace result could not be reconciled"),
+        cause: expect.any(Error),
+      });
+
+      expect(placements.get(SESSION_ID)).toMatchObject({
+        state: "active",
+        generation: original.generation,
+        environmentId: original.environmentId,
+        activeOwnerEpoch: original.activeOwnerEpoch,
+        workspaceBaseManifestRef: original.workspaceBaseManifestRef,
+        turnClaim: null,
+        terminalReason: null,
+      });
+      expect(placements.listPendingWorkspaceResults()).toEqual([]);
+      expect(reconcileWorkspace).not.toHaveBeenCalled();
+      expect(reconcileActivePlacement).not.toHaveBeenCalled();
+
+      connected = true;
+      await expect(
+        provider.executeTurn(
+          {
+            sessionId: SESSION_ID,
+            sessionKey: SESSION_KEY,
+            agentId: "main",
+            runId: "run-paired-device-fresh-attempt",
+          },
+          turn("run-paired-device-fresh-attempt"),
+          async () => ({ payloads: [{ text: "fresh node attempt" }], meta: { durationMs: 1 } }),
+        ),
+      ).resolves.toMatchObject({ payloads: [{ text: "fresh node attempt" }] });
+
+      expect(reconcileWorkspace).toHaveBeenCalledWith(
+        expect.objectContaining({ baseManifestRef: original.workspaceBaseManifestRef }),
+      );
+      expect(launchTurn).not.toHaveBeenCalled();
+      expect(placements.get(SESSION_ID)).toMatchObject({ state: "active", turnClaim: null });
+    },
+  );
+
   it("rejects a reused worker bundle without execution context before launch", async () => {
     seedActivePlacement();
     const oldEnvironment = attachedEnvironment();
diff --git a/src/gateway/worker-environments/worker-turn-launcher.ts b/src/gateway/worker-environments/worker-turn-launcher.ts
index be6d4ae2b239..7dc7e4f24c64 100644
--- a/src/gateway/worker-environments/worker-turn-launcher.ts
+++ b/src/gateway/worker-environments/worker-turn-launcher.ts
@@ -442,14 +442,25 @@ export function createWorkerSessionTurnPlacementProvider(options: WorkerTurnLaun
         agentId: placement.agentId,
         sessionKey: placement.sessionKey,
       });
-      if (!options.environments.resolveSshIdentity) {
-        throw new Error("Remote-exec sandbox identity resolver is unavailable");
+      const preparedPlacement = options.placements.get(params.sessionId);
+      if (
+        preparedPlacement?.state !== "active" ||
+        preparedPlacement.executionMode !== "remote-exec" ||
+        preparedPlacement.agentId !== placement.agentId ||
+        preparedPlacement.sessionKey !== placement.sessionKey ||
+        preparedPlacement.environmentId !== placement.environmentId ||
+        preparedPlacement.activeOwnerEpoch !== placement.activeOwnerEpoch ||
+        preparedPlacement.generation !== placement.generation
+      ) {
+        throw new Error("Remote-exec placement changed while preparing its managed workspace");
       }
       const sandbox = await createRemoteExecPlacementSandbox({
         config: params.config,
         environments: {
           get: options.environments.get,
-          resolveSshIdentity: options.environments.resolveSshIdentity,
+          ...(options.environments.resolveSshIdentity
+            ? { resolveSshIdentity: options.environments.resolveSshIdentity }
+            : {}),
         },
         localWorkspaceDir,
         placement,
@@ -458,12 +469,27 @@ export function createWorkerSessionTurnPlacementProvider(options: WorkerTurnLaun
       if (
         current?.state !== "active" ||
         current.executionMode !== "remote-exec" ||
+        current.agentId !== placement.agentId ||
+        current.sessionKey !== placement.sessionKey ||
         current.environmentId !== placement.environmentId ||
         current.activeOwnerEpoch !== placement.activeOwnerEpoch ||
         current.generation !== placement.generation
       ) {
         throw new Error("Remote-exec placement changed while preparing its sandbox");
       }
+      const currentEnvironment = options.environments.get(placement.environmentId);
+      if (
+        currentEnvironment?.state !== "attached" ||
+        currentEnvironment.environmentId !== placement.environmentId ||
+        currentEnvironment.ownerEpoch !== placement.activeOwnerEpoch ||
+        currentEnvironment.attachedSessionIds.length !== 1 ||
+        currentEnvironment.attachedSessionIds[0] !== placement.sessionId ||
+        (sandbox.backendId === "node" &&
+          "placementNodeId" in sandbox &&
+          currentEnvironment.nodeDeviceId !== sandbox.placementNodeId)
+      ) {
+        throw new Error("Remote-exec environment changed while preparing its sandbox");
+      }
       return sandbox;
     },
     async executeLocalTurn<T>(claim: LocalTurnPlacementClaim, runLocal: () => Promise<T>) {
diff --git a/src/gateway/worker-environments/workspace-result-finalize.ts b/src/gateway/worker-environments/workspace-result-finalize.ts
index 65113aca3532..6cfa6357199a 100644
--- a/src/gateway/worker-environments/workspace-result-finalize.ts
+++ b/src/gateway/worker-environments/workspace-result-finalize.ts
@@ -4,13 +4,14 @@ import type { SessionPlacementTurnParams } from "../../agents/session-placement-
 import { SessionManager } from "../../agents/sessions/session-manager.js";
 import { formatErrorMessage } from "../../infra/errors.js";
 import { redactSensitiveText } from "../../logging/redact.js";
+import { DEVICE_WORKER_PROVIDER_ID } from "./device-provider-identity.js";
 import type {
   WorkerSessionPlacementRecord,
   WorkerSessionPlacementStore,
   WorkerSessionTurnClaim,
 } from "./placement-store.js";
 import type { WorkerEnvironmentService } from "./service.js";
-import type { WorkerTunnelHandle } from "./tunnel-contract.js";
+import { WorkerTunnelOwnerDisconnectedError, type WorkerTunnelHandle } from "./tunnel-contract.js";
 import { latestDurableWorkspaceConflict, waitForTurnOperation } from "./worker-turn-admission.js";
 import { resolveWorkerTurnTranscriptTarget } from "./worker-turn-transcript-target.js";
 import {
@@ -332,6 +333,31 @@ export async function executeRemoteExecTurn(params: {
     ...(params.publishAcceptedWorkspace
       ? { publishAcceptedWorkspace: params.publishAcceptedWorkspace }
       : {}),
+  }).catch((reconciliationError: unknown) => {
+    const currentEnvironment = params.environments.get(params.placement.environmentId);
+    if (
+      environment.providerId === DEVICE_WORKER_PROVIDER_ID &&
+      environment.nodeDeviceId &&
+      currentEnvironment?.state === "attached" &&
+      currentEnvironment.providerId === DEVICE_WORKER_PROVIDER_ID &&
+      currentEnvironment.environmentId === environment.environmentId &&
+      currentEnvironment.ownerEpoch === environment.ownerEpoch &&
+      currentEnvironment.nodeDeviceId === environment.nodeDeviceId &&
+      currentEnvironment.attachedSessionIds.length === 1 &&
+      currentEnvironment.attachedSessionIds[0] === params.placement.sessionId &&
+      reconciliationError instanceof WorkerWorkspaceReconciliationError &&
+      reconciliationError.cause instanceof WorkerTunnelOwnerDisconnectedError
+    ) {
+      // Offline paired nodes keep their exact lease; the next turn reconciles its dirty workspace.
+      params.placements.cancelWorkspaceResultAndReleaseTurn(params.turnClaim, {
+        reason: "node-disconnect",
+      });
+    }
+    if (executionError) {
+      // Preserve the terminal execution failure while retaining the independent workspace loss.
+      throw new Error(formatErrorMessage(executionError), { cause: reconciliationError });
+    }
+    throw reconciliationError;
   });
   if (executionError) {
     throw executionError instanceof Error
diff --git a/src/infra/node-duplex-framing.test.ts b/src/infra/node-duplex-framing.test.ts
index 03b5d219e24e..78be0562b488 100644
--- a/src/infra/node-duplex-framing.test.ts
+++ b/src/infra/node-duplex-framing.test.ts
@@ -300,6 +300,19 @@ describe("node duplex message framing", () => {
     },
   );
 
+  it.each([0, 15, 16.5, Number.NaN, MAX_MESSAGE_BYTES + 1])(
+    "rejects an unsafe outstanding delivery limit of %s bytes",
+    (maxOutstandingDeliveryBytes) => {
+      expect(() =>
+        createNodeDuplexEndpoint({
+          sendFrame: () => {},
+          maxMessageBytes: 16,
+          maxOutstandingDeliveryBytes,
+        }),
+      ).toThrow(/outstanding delivery/i);
+    },
+  );
+
   it("rejects accumulated message overflow and excessive fragment counts", () => {
     const fragment = Buffer.alloc(FRAGMENT_BYTES).toString("base64");
     const overflow = createNodeDuplexEndpoint({
@@ -405,6 +418,79 @@ describe("node duplex message framing", () => {
     expect(onError).toHaveBeenCalledOnce();
   });
 
+  it("enforces an expanded aggregate delivery budget independently of the message ceiling", () => {
+    const onError = vi.fn();
+    const listener = vi.fn(() => new Promise<void>(() => {}));
+    const endpoint = createNodeDuplexEndpoint({
+      sendFrame: () => {},
+      onError,
+      maxMessageBytes: 16,
+      maxOutstandingDeliveryBytes: 24,
+    });
+    endpoint.onMessage(listener);
+    endpoint.receive(dataFrame({ data: Buffer.alloc(16).toString("base64") }));
+    endpoint.receive(dataFrame({ message: 1, data: Buffer.alloc(8).toString("base64") }));
+
+    expect(() => endpoint.receive(dataFrame({ message: 2, data: "eA==" }))).toThrow(/pending/i);
+    expect(listener).toHaveBeenCalledTimes(2);
+    expect(onError).toHaveBeenCalledOnce();
+  });
+
+  it("delivers an exact-limit response and bounded following notification before either delivery settles", async () => {
+    const maxMessageBytes = 64 * 1024 * 1024;
+    const maxOutstandingDeliveryBytes = maxMessageBytes + 2 * 1024 * 1024;
+    const received: Uint8Array[] = [];
+    let finishDeliveries: (() => void) | undefined;
+    const deliveriesFinished = new Promise<void>((resolve) => {
+      finishDeliveries = resolve;
+    });
+    const receiver = createNodeDuplexEndpoint({
+      sendFrame: () => {},
+      maxMessageBytes,
+      maxOutstandingDeliveryBytes,
+    });
+    receiver.onMessage((message) => {
+      received.push(message);
+      return deliveriesFinished;
+    });
+    const sender = createNodeDuplexEndpoint({
+      sendFrame: (frame) => receiver.receive(frame),
+      maxMessageBytes,
+      maxOutstandingDeliveryBytes,
+    });
+    const response = Buffer.alloc(maxMessageBytes, 0x78);
+    const responseStart = Buffer.from('{"jsonrpc":"2.0","id":1,"result":"');
+    const responseEnd = Buffer.from('"}');
+    responseStart.copy(response);
+    responseEnd.copy(response, response.length - responseEnd.length);
+    const notification = Buffer.from(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        method: "http/request/bodyDelta",
+        params: {
+          requestId: "response-at-limit",
+          seq: 1,
+          deltaBase64: Buffer.alloc(1024 * 1024).toString("base64"),
+          done: false,
+        },
+      }),
+    );
+
+    try {
+      await sender.send(response);
+      await sender.send(notification);
+      expect(received.map((message) => message.byteLength)).toEqual([
+        maxMessageBytes,
+        notification.byteLength,
+      ]);
+      await expect(sender.send(new Uint8Array(maxMessageBytes + 1))).rejects.toThrow(/maximum/i);
+    } finally {
+      finishDeliveries?.();
+    }
+
+    await receiver.drain();
+  });
+
   it.each(["immediate", "buffered"] as const)(
     "drains an asynchronous %s listener before allowing invocation completion",
     async (delivery) => {
diff --git a/src/infra/node-duplex-framing.ts b/src/infra/node-duplex-framing.ts
index 5b5aa3380c5a..6e3ab6bf9198 100644
--- a/src/infra/node-duplex-framing.ts
+++ b/src/infra/node-duplex-framing.ts
@@ -14,12 +14,23 @@ export function createNodeDuplexEndpoint(options: {
   onError?: (error: Error) => void;
   requireReady?: boolean;
   maxMessageBytes?: number;
+  maxOutstandingDeliveryBytes?: number;
 }) {
   const maxMessageBytes = options.maxMessageBytes ?? NODE_DUPLEX_MAX_MESSAGE_BYTES;
   const invalidMessageLimit = !Number.isSafeInteger(maxMessageBytes) || maxMessageBytes < 1;
   if (invalidMessageLimit || maxMessageBytes > NODE_DUPLEX_MAX_MESSAGE_BYTES) {
     throw new Error("node duplex maximum message bytes must be between 1 and 100 MiB");
   }
+  const maxOutstandingDeliveryBytes = options.maxOutstandingDeliveryBytes ?? maxMessageBytes;
+  if (
+    !Number.isSafeInteger(maxOutstandingDeliveryBytes) ||
+    maxOutstandingDeliveryBytes < maxMessageBytes ||
+    maxOutstandingDeliveryBytes > NODE_DUPLEX_MAX_MESSAGE_BYTES
+  ) {
+    throw new Error(
+      "node duplex maximum outstanding delivery bytes must be between the message limit and 100 MiB",
+    );
+  }
   let closed = false;
   const ready = { sent: false, received: false };
   let nextOutgoingMessage = 0;
@@ -67,7 +78,7 @@ export function createNodeDuplexEndpoint(options: {
   };
 
   const observeListener = (callback: NonNullable<typeof listener>, message: Uint8Array) => {
-    const bytesExceeded = activeDeliveryBytes + message.byteLength > maxMessageBytes;
+    const bytesExceeded = activeDeliveryBytes + message.byteLength > maxOutstandingDeliveryBytes;
     if (activeDeliveries.size >= MAX_PENDING_MESSAGES || bytesExceeded) {
       throw new Error("node duplex pending listener delivery exceeded its bounded capacity");
     }
diff --git a/src/node-host/invoke-payload.test.ts b/src/node-host/invoke-payload.test.ts
index 975eb45a8ce1..18e84225c630 100644
--- a/src/node-host/invoke-payload.test.ts
+++ b/src/node-host/invoke-payload.test.ts
@@ -1,5 +1,32 @@
 import { describe, expect, it } from "vitest";
-import { coerceNodeInvokeInputPayload } from "./invoke-payload.js";
+import { coerceNodeInvokeInputPayload, coerceNodeInvokePayload } from "./invoke-payload.js";
+
+describe("coerceNodeInvokePayload", () => {
+  it.each([
+    ["preserves the exact owning session", "agent:main:managed", "agent:main:managed"],
+    ["normalizes the owning session", "  agent:main:managed  ", "agent:main:managed"],
+    ["omits an absent owning session", undefined, undefined],
+    ["omits a blank owning session", "  ", undefined],
+    ["omits a non-string owning session", 42, undefined],
+  ])("%s", (_name, sessionKey, expectedSessionKey) => {
+    expect(
+      coerceNodeInvokePayload({
+        id: "invoke-1",
+        nodeId: "node-1",
+        command: "plugin.workspace",
+        sessionKey,
+      }),
+    ).toEqual({
+      id: "invoke-1",
+      nodeId: "node-1",
+      command: "plugin.workspace",
+      paramsJSON: null,
+      timeoutMs: null,
+      idempotencyKey: null,
+      ...(expectedSessionKey ? { sessionKey: expectedSessionKey } : {}),
+    });
+  });
+});
 
 describe("coerceNodeInvokeInputPayload", () => {
   it("accepts a bounded well-formed input payload", () => {
diff --git a/src/node-host/invoke-payload.ts b/src/node-host/invoke-payload.ts
index e9bdcaadd1cd..b397f577488e 100644
--- a/src/node-host/invoke-payload.ts
+++ b/src/node-host/invoke-payload.ts
@@ -1,3 +1,4 @@
+import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { NodeInvokeRequestPayload } from "./invoke-types.js";
 
 const MAX_INVOKE_INPUT_BYTES = 16 * 1024;
@@ -21,6 +22,7 @@ export function coerceNodeInvokePayload(payload: unknown): NodeInvokeRequestPayl
         : null;
   const timeoutMs = typeof obj.timeoutMs === "number" ? obj.timeoutMs : null;
   const idempotencyKey = typeof obj.idempotencyKey === "string" ? obj.idempotencyKey : null;
+  const sessionKey = normalizeOptionalString(obj.sessionKey);
   return {
     id,
     nodeId,
@@ -28,6 +30,7 @@ export function coerceNodeInvokePayload(payload: unknown): NodeInvokeRequestPayl
     paramsJSON,
     timeoutMs,
     idempotencyKey,
+    ...(sessionKey ? { sessionKey } : {}),
   };
 }
 
diff --git a/src/node-host/invoke.test.ts b/src/node-host/invoke.test.ts
index d969be439ecb..09ef31b860cd 100644
--- a/src/node-host/invoke.test.ts
+++ b/src/node-host/invoke.test.ts
@@ -8,6 +8,10 @@ import type { GatewayClient } from "../gateway/client.js";
 import { saveExecApprovals, type ExecApprovalsSnapshot } from "../infra/exec-approvals.js";
 import { createEmptyPluginRegistry } from "../plugins/registry-empty.js";
 import { resetPluginRuntimeStateForTest, setActivePluginRegistry } from "../plugins/runtime.js";
+import type {
+  OpenClawPluginNodeHostCommand,
+  OpenClawPluginNodeHostCommandContext,
+} from "../plugins/types.node-host.js";
 import { closeOpenClawStateDatabaseForTest } from "../state/openclaw-state-db.js";
 import { withEnvAsync } from "../test-utils/env.js";
 import type { SkillBinsProvider } from "./invoke-types.js";
@@ -194,6 +198,68 @@ describe("node host invoke", () => {
     });
   });
 
+  it("binds managed workspace claims to the exact live plugin invocation session", async () => {
+    const release = vi.fn();
+    const acquireManagedWorkspace = vi.fn(() => ({ workspaceDir: "/managed", release }));
+    const workspaceRequest = {
+      workspaceDir: "/managed",
+      environmentId: "environment-1",
+      sessionId: "session-1",
+      ownerEpoch: 1,
+      sessionKey: "agent:main:managed",
+    };
+    let retainedAcquire:
+      | NonNullable<OpenClawPluginNodeHostCommandContext["acquireManagedWorkspace"]>
+      | undefined;
+    const handle = vi.fn<OpenClawPluginNodeHostCommand["handle"]>(
+      async (_paramsJSON, _io, context) => {
+        const acquire = context?.acquireManagedWorkspace;
+        if (!acquire) {
+          throw new Error("managed workspace authority missing");
+        }
+        retainedAcquire = acquire;
+        expect(() => acquire({ ...workspaceRequest, sessionKey: "agent:main:other" })).toThrow(
+          "workspace invocation authority is closed",
+        );
+        expect(acquire(workspaceRequest)).toEqual({
+          workspaceDir: "/managed",
+          release,
+        });
+        return '{"ok":true}';
+      },
+    );
+    const registry = createEmptyPluginRegistry();
+    registry.nodeHostCommands = [
+      {
+        pluginId: "workspace-plugin",
+        pluginName: "Workspace Plugin",
+        command: { command: "workspace.claim", handle },
+        source: "test",
+      },
+    ];
+    setActivePluginRegistry(registry);
+    const request = vi.fn<GatewayClient["request"]>().mockResolvedValue(null);
+
+    await handleInvoke(
+      {
+        id: "invoke-workspace",
+        nodeId: "node-1",
+        command: "workspace.claim",
+        paramsJSON: "{}",
+        sessionKey: workspaceRequest.sessionKey,
+      },
+      { request } as unknown as GatewayClient,
+      { current: async () => [] },
+      undefined,
+      { pluginCommandContext: { sendNodeEvent: vi.fn(), acquireManagedWorkspace } },
+    );
+
+    expect(acquireManagedWorkspace).toHaveBeenCalledOnce();
+    expect(() => retainedAcquire?.(workspaceRequest)).toThrow(
+      "workspace invocation authority is closed",
+    );
+  });
+
   it("does not publish a canceled non-duplex plugin result", async () => {
     const controller = new AbortController();
     let resolvePlugin: ((result: string) => void) | undefined;
diff --git a/src/node-host/invoke.ts b/src/node-host/invoke.ts
index 1430b5f9e803..e0bd38cd60ff 100644
--- a/src/node-host/invoke.ts
+++ b/src/node-host/invoke.ts
@@ -820,15 +820,39 @@ async function dispatchInvoke(
   }
   try {
     const { pluginCommandIo: io, pluginCommandContext: context } = runtime;
+    const acquireManagedWorkspace = context?.acquireManagedWorkspace;
+    let pluginInvocationActive = true;
     const invokeContext =
-      context && (frame.sessionKey || runtime.signal)
+      context && (frame.sessionKey || runtime.signal || acquireManagedWorkspace)
         ? {
             ...context,
             ...(frame.sessionKey ? { sessionKey: frame.sessionKey } : {}),
             ...(runtime.signal ? { signal: runtime.signal } : {}),
+            ...(acquireManagedWorkspace
+              ? {
+                  acquireManagedWorkspace: (
+                    request: Parameters<typeof acquireManagedWorkspace>[0],
+                  ) => {
+                    if (
+                      !pluginInvocationActive ||
+                      runtime.signal?.aborted ||
+                      !frame.sessionKey ||
+                      request.sessionKey !== frame.sessionKey
+                    ) {
+                      throw new Error("node placement workspace invocation authority is closed");
+                    }
+                    return acquireManagedWorkspace(request);
+                  },
+                }
+              : {}),
           }
         : context;
-    const pluginResult = await invokePlugin(command, frame.paramsJSON, io, invokeContext);
+    let pluginResult: string | null;
+    try {
+      pluginResult = await invokePlugin(command, frame.paramsJSON, io, invokeContext);
+    } finally {
+      pluginInvocationActive = false;
+    }
     if (pluginResult !== null) {
       await runtime.flushPluginCommandIo?.();
       await sendRawPayloadResult(client, frame, pluginResult);
diff --git a/src/node-host/node-worker-workspace-identity.ts b/src/node-host/node-worker-workspace-identity.ts
new file mode 100644
index 000000000000..09034a8ae4c0
--- /dev/null
+++ b/src/node-host/node-worker-workspace-identity.ts
@@ -0,0 +1,137 @@
+/** Validates node-owned placement workspace identities and canonical paths. */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { isPathInside } from "../infra/path-guards.js";
+
+const GATEWAY_NAMESPACE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+
+export type NodeWorkerManagedWorkspaceRequest = {
+  workspaceDir: string;
+  environmentId: string;
+  sessionId: string;
+  ownerEpoch: number;
+  sessionKey: string;
+};
+
+export function hashNodeWorkerWorkspaceComponent(value: string, length: number): string {
+  return createHash("sha256").update(value).digest("hex").slice(0, length);
+}
+
+export function nodeWorkerWorkspaceGenerationKey(params: {
+  gatewayNamespace: string;
+  environmentHash: string;
+  sessionHash: string;
+  generation: number;
+}): string {
+  return [
+    params.gatewayNamespace,
+    params.environmentHash,
+    params.sessionHash,
+    params.generation,
+  ].join("/");
+}
+
+export function nodeWorkerWorkspaceLaunchGenerationKey(reference: {
+  gatewayNamespace: string;
+  environmentId: string;
+  sessionId: string;
+  ownerEpoch: number;
+}): string {
+  return nodeWorkerWorkspaceGenerationKey({
+    gatewayNamespace: reference.gatewayNamespace,
+    environmentHash: hashNodeWorkerWorkspaceComponent(reference.environmentId, 16),
+    sessionHash: hashNodeWorkerWorkspaceComponent(reference.sessionId, 32),
+    generation: reference.ownerEpoch,
+  });
+}
+
+export function nodeWorkerWorkspaceSessionKey(
+  environmentHash: string,
+  sessionHash: string,
+): string {
+  return `${environmentHash}/${sessionHash}`;
+}
+
+export function parseNodeWorkerWorkspaceGeneration(name: string): number | undefined {
+  const generation = Number(name);
+  return Number.isSafeInteger(generation) && generation >= 0 && String(generation) === name
+    ? generation
+    : undefined;
+}
+
+export function parseNodeWorkerWorkspaceTransferGeneration(name: string): number | undefined {
+  const staging = /^\.([0-9]+)\.workspace-transfer-.+$/u.exec(name)?.[1];
+  const backup = /^([0-9]+)\.previous-.+$/u.exec(name)?.[1];
+  const generation = staging ?? backup;
+  return generation === undefined ? undefined : parseNodeWorkerWorkspaceGeneration(generation);
+}
+
+/** Proves an existing workspace was derived from its exact node-owned placement identity. */
+export function resolveNodeManagedWorkspaceIdentity(
+  root: string,
+  request: NodeWorkerManagedWorkspaceRequest,
+): { workspaceDir: string; gatewayNamespace: string; generationKey: string } {
+  const fail = () => {
+    throw new Error("INVALID_REQUEST: node placement does not own the requested workspace");
+  };
+  if (
+    typeof request.workspaceDir !== "string" ||
+    !path.isAbsolute(request.workspaceDir) ||
+    typeof request.environmentId !== "string" ||
+    !request.environmentId ||
+    typeof request.sessionId !== "string" ||
+    !request.sessionId ||
+    typeof request.sessionKey !== "string" ||
+    !request.sessionKey ||
+    !Number.isSafeInteger(request.ownerEpoch) ||
+    request.ownerEpoch < 1
+  ) {
+    return fail();
+  }
+
+  let stats: fs.Stats;
+  let workspaceDir: string;
+  try {
+    stats = fs.lstatSync(request.workspaceDir);
+    workspaceDir = fs.realpathSync.native(request.workspaceDir);
+  } catch {
+    return fail();
+  }
+  const components = path.relative(root, workspaceDir).split(path.sep);
+  const gatewayNamespace = components[0];
+  if (!gatewayNamespace || !GATEWAY_NAMESPACE_PATTERN.test(gatewayNamespace)) {
+    return fail();
+  }
+  const environmentHash = hashNodeWorkerWorkspaceComponent(request.environmentId, 16);
+  const sessionHash = hashNodeWorkerWorkspaceComponent(request.sessionId, 32);
+  const expected = path.join(
+    root,
+    gatewayNamespace,
+    "workspaces",
+    environmentHash,
+    sessionHash,
+    String(request.ownerEpoch),
+  );
+  if (
+    stats.isSymbolicLink() ||
+    !stats.isDirectory() ||
+    !isPathInside(root, workspaceDir) ||
+    components.length !== 5 ||
+    components[1] !== "workspaces" ||
+    request.workspaceDir !== workspaceDir ||
+    workspaceDir !== expected
+  ) {
+    return fail();
+  }
+  return {
+    workspaceDir,
+    gatewayNamespace,
+    generationKey: nodeWorkerWorkspaceGenerationKey({
+      gatewayNamespace,
+      environmentHash,
+      sessionHash,
+      generation: request.ownerEpoch,
+    }),
+  };
+}
diff --git a/src/node-host/node-worker-workspace-retention.test.ts b/src/node-host/node-worker-workspace-retention.test.ts
index 8c90defc4f45..579a832e03d4 100644
--- a/src/node-host/node-worker-workspace-retention.test.ts
+++ b/src/node-host/node-worker-workspace-retention.test.ts
@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
+import fsp from "node:fs/promises";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { useAutoCleanupTempDirTracker } from "../../test/helpers/temp-dir.js";
@@ -97,6 +98,111 @@ afterEach(() => {
 });
 
 describe("node worker workspace retention", () => {
+  it("claims only the exact canonical placement workspace identity", () => {
+    const root = fs.realpathSync.native(tempDirs.make("node-worker-workspace-managed-identity-"));
+    const workspace = new NodeWorkerWorkspaceRuntime({ root });
+    const input = testWorkerLaunchInput("/unused", "managed-identity");
+    const ownerEpoch = input.descriptor.admission.ownerEpoch;
+    const workspaceDir = seedGeneration(root, input, ownerEpoch);
+    const request = {
+      workspaceDir,
+      environmentId: input.descriptor.admission.environmentId,
+      sessionId: input.descriptor.admission.sessionId,
+      ownerEpoch,
+      sessionKey: "agent:main:managed",
+    };
+
+    const claim = workspace.acquireManagedWorkspace(request);
+    expect(claim.workspaceDir).toBe(workspaceDir);
+    claim.release();
+    claim.release();
+
+    for (const changed of [
+      { workspaceDir: root },
+      { environmentId: "different-environment" },
+      { sessionId: "different-session" },
+      { ownerEpoch: ownerEpoch + 1 },
+      { sessionKey: "" },
+    ]) {
+      expect(() => workspace.acquireManagedWorkspace({ ...request, ...changed })).toThrow(
+        "does not own the requested workspace",
+      );
+    }
+
+    const linked = path.join(path.dirname(workspaceDir), "linked-workspace");
+    fs.symlinkSync(workspaceDir, linked, process.platform === "win32" ? "junction" : "dir");
+    expect(() => workspace.acquireManagedWorkspace({ ...request, workspaceDir: linked })).toThrow(
+      "does not own the requested workspace",
+    );
+  });
+
+  it("protects a claimed placement workspace until its owner releases it", async () => {
+    const root = fs.realpathSync.native(tempDirs.make("node-worker-workspace-managed-retention-"));
+    const workspace = new NodeWorkerWorkspaceRuntime({ root });
+    const input = testWorkerLaunchInput("/unused", "managed-retention");
+    const ownerEpoch = input.descriptor.admission.ownerEpoch;
+    const workspaceDir = seedGeneration(root, input, ownerEpoch);
+    const claim = workspace.acquireManagedWorkspace({
+      workspaceDir,
+      environmentId: input.descriptor.admission.environmentId,
+      sessionId: input.descriptor.admission.sessionId,
+      ownerEpoch,
+      sessionKey: "agent:main:managed",
+    });
+
+    await workspace.applyRetainSnapshot(retainInput(input, 1, []), () => []);
+    expect(fs.existsSync(workspaceDir)).toBe(true);
+
+    claim.release();
+    claim.release();
+    await workspace.applyRetainSnapshot(retainInput(input, 2, []), () => []);
+    expect(fs.existsSync(workspaceDir)).toBe(false);
+  });
+
+  it("rejects a placement claim once workspace removal is already in flight", async () => {
+    const root = fs.realpathSync.native(tempDirs.make("node-worker-workspace-removal-race-"));
+    const workspace = new NodeWorkerWorkspaceRuntime({ root });
+    const input = testWorkerLaunchInput("/unused", "managed-removal-race");
+    const ownerEpoch = input.descriptor.admission.ownerEpoch;
+    const workspaceDir = seedGeneration(root, input, ownerEpoch);
+    const request = {
+      workspaceDir,
+      environmentId: input.descriptor.admission.environmentId,
+      sessionId: input.descriptor.admission.sessionId,
+      ownerEpoch,
+      sessionKey: "agent:main:managed",
+    };
+    let started!: () => void;
+    let finish!: () => void;
+    const removalStarted = new Promise<void>((resolve) => {
+      started = resolve;
+    });
+    const finishRemoval = new Promise<void>((resolve) => {
+      finish = resolve;
+    });
+    const remove = fsp.rm.bind(fsp);
+    vi.spyOn(fsp, "rm").mockImplementation(async (target, options) => {
+      if (String(target) === workspaceDir) {
+        started();
+        await finishRemoval;
+      }
+      return await remove(target, options);
+    });
+    const retention = workspace.applyRetainSnapshot(retainInput(input, 1, []), () => []);
+
+    try {
+      await removalStarted;
+      expect(fs.existsSync(workspaceDir)).toBe(true);
+      expect(() => workspace.acquireManagedWorkspace(request)).toThrow(
+        "workspace is being removed",
+      );
+    } finally {
+      finish();
+      await retention;
+    }
+    expect(fs.existsSync(workspaceDir)).toBe(false);
+  });
+
   it("does not delete workspaces before the first Gateway snapshot", async () => {
     const root = tempDirs.make("node-worker-workspace-retention-startup-");
     const { bundleRoot, env, workspaceDir } = writeNodeWorkerFixture(root);
diff --git a/src/node-host/node-worker-workspace.ts b/src/node-host/node-worker-workspace.ts
index bed77adc430c..87b80b017492 100644
--- a/src/node-host/node-worker-workspace.ts
+++ b/src/node-host/node-worker-workspace.ts
@@ -1,4 +1,3 @@
-import { createHash } from "node:crypto";
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
@@ -23,6 +22,16 @@ import {
   runNodeWorkerWorkspaceTransfer,
   serializeNodeWorkerWorkspace,
 } from "./node-worker-transfer-client.js";
+import {
+  hashNodeWorkerWorkspaceComponent as hashPathComponent,
+  nodeWorkerWorkspaceGenerationKey as workspaceGenerationKey,
+  nodeWorkerWorkspaceLaunchGenerationKey as launchGenerationKey,
+  nodeWorkerWorkspaceSessionKey as workspaceSessionKey,
+  parseNodeWorkerWorkspaceGeneration as parseGenerationName,
+  parseNodeWorkerWorkspaceTransferGeneration as parseTransferArtifactGeneration,
+  resolveNodeManagedWorkspaceIdentity,
+  type NodeWorkerManagedWorkspaceRequest,
+} from "./node-worker-workspace-identity.js";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
 const WORKSPACE_RETENTION_DELETE_LIMIT = 256;
@@ -54,53 +63,6 @@ type AcceptedRetainSnapshot = {
   manifestsBySession: Map<string, Set<string> | null>;
 };
 
-function hashPathComponent(value: string, length: number): string {
-  return createHash("sha256").update(value).digest("hex").slice(0, length);
-}
-
-function workspaceGenerationKey(params: {
-  gatewayNamespace: string;
-  environmentHash: string;
-  sessionHash: string;
-  generation: number;
-}): string {
-  return [
-    params.gatewayNamespace,
-    params.environmentHash,
-    params.sessionHash,
-    params.generation,
-  ].join("/");
-}
-
-function launchGenerationKey(reference: NodeWorkerWorkspaceLaunchReference): string {
-  return workspaceGenerationKey({
-    gatewayNamespace: reference.gatewayNamespace,
-    environmentHash: hashPathComponent(reference.environmentId, 16),
-    sessionHash: hashPathComponent(reference.sessionId, 32),
-    generation: reference.ownerEpoch,
-  });
-}
-
-function workspaceSessionKey(environmentHash: string, sessionHash: string): string {
-  return `${environmentHash}/${sessionHash}`;
-}
-
-function parseGenerationName(name: string): number | undefined {
-  const generation = Number(name);
-  return Number.isSafeInteger(generation) && generation >= 0 && String(generation) === name
-    ? generation
-    : undefined;
-}
-
-function parseTransferArtifactGeneration(name: string): number | undefined {
-  const staging = /^\.([0-9]+)\.workspace-transfer-.+$/u.exec(name);
-  if (staging) {
-    return parseGenerationName(staging[1]!);
-  }
-  const backup = /^([0-9]+)\.previous-.+$/u.exec(name);
-  return backup ? parseGenerationName(backup[1]!) : undefined;
-}
-
 async function listOwnedEntries(parent: string): Promise<fs.Dirent[]> {
   try {
     return (await fsp.readdir(parent, { withFileTypes: true })).toSorted((left, right) =>
@@ -318,6 +280,7 @@ export class NodeWorkerWorkspaceRuntime {
   private readonly retainQueue = new KeyedAsyncQueue();
   private readonly acceptedSnapshots = new Map<string, AcceptedRetainSnapshot>();
   private readonly activeWorkspaceOperations = new Map<string, number>();
+  private readonly deletingWorkspaceGenerations = new Set<string>();
   private readonly activeRetainProtections = new Map<string, Set<Set<string>>>();
 
   constructor(options: { root?: string; env?: NodeJS.ProcessEnv } = {}) {
@@ -338,6 +301,31 @@ export class NodeWorkerWorkspaceRuntime {
     };
   }
 
+  /** Claims an existing identity-derived workspace against concurrent retention. */
+  acquireManagedWorkspace(request: NodeWorkerManagedWorkspaceRequest): {
+    workspaceDir: string;
+    release: () => void;
+  } {
+    const identity = resolveNodeManagedWorkspaceIdentity(this.root, request);
+    if (this.deletingWorkspaceGenerations.has(identity.generationKey)) {
+      throw new Error("INVALID_REQUEST: node placement workspace is being removed");
+    }
+    const finishOperation = this.beginWorkspaceOperation(
+      identity.gatewayNamespace,
+      identity.generationKey,
+    );
+    let released = false;
+    return {
+      workspaceDir: identity.workspaceDir,
+      release: () => {
+        if (!released) {
+          released = true;
+          finishOperation();
+        }
+      },
+    };
+  }
+
   private beginWorkspaceOperation(gatewayNamespace: string, generationKey: string): () => void {
     this.activeWorkspaceOperations.set(
       generationKey,
@@ -526,16 +514,20 @@ export class NodeWorkerWorkspaceRuntime {
             continue;
           }
           if (
-            await removeOwnedDirectory(
-              this.root,
-              candidate.path,
-              () =>
-                !this.currentLocalProtection(
+            await removeOwnedDirectory(this.root, candidate.path, () => {
+              if (
+                this.currentLocalProtection(
                   params.gatewayNamespace,
                   params.retainedDuringPass,
                   params.listNonterminal,
-                ).has(candidate.generationKey),
-            )
+                ).has(candidate.generationKey)
+              ) {
+                return false;
+              }
+              // No claim may begin after this final check and before recursive removal settles.
+              this.deletingWorkspaceGenerations.add(candidate.generationKey);
+              return true;
+            }).finally(() => this.deletingWorkspaceGenerations.delete(candidate.generationKey))
           ) {
             deleted += 1;
           }
diff --git a/src/node-host/runtime.ts b/src/node-host/runtime.ts
index f2dc073c0b9f..85edfde851b8 100644
--- a/src/node-host/runtime.ts
+++ b/src/node-host/runtime.ts
@@ -350,6 +350,12 @@ export async function prepareNodeHostRuntime(params?: {
       const pluginCommandContext: OpenClawPluginNodeHostCommandContext = {
         sendNodeEvent: async (event, payload) =>
           await client.request("node.event", buildNodeEventParams(event, payload)),
+        ...(workerWorkspace
+          ? {
+              acquireManagedWorkspace: (request) =>
+                workerWorkspace.acquireManagedWorkspace(request),
+            }
+          : {}),
       };
       let currentPluginNodeHost = pluginNodeHost;
       let currentManifest = manifest;
diff --git a/src/plugins/capability-provider.types.ts b/src/plugins/capability-provider.types.ts
index c0aab747cb9f..12753740a7d9 100644
--- a/src/plugins/capability-provider.types.ts
+++ b/src/plugins/capability-provider.types.ts
@@ -188,13 +188,15 @@ export class WorkerProviderError extends Error {
   }
 }
 
-/** Cloud-worker lifecycle capability registered by a plugin. */
-export type WorkerProvider = {
+/** Plugin registrations declare exactly one mode; the internal paired-device owner can carry both. */
+export type WorkerProvider<Scope extends "plugin" | "internal" = "plugin"> = {
   id: string;
   /** Process-stable choices available for this profile; omit the hook to hide machine selection. */
   listMachineOptions?: (profile: WorkerProfile) => Promise<readonly WorkerMachineOption[]>;
-  /** Omission advertises no placement support; placement providers declare one transport mode. */
-  supportedExecutionModes?: readonly [WorkerExecutionMode];
+  /** Omission advertises no placement support; external providers declare one transport mode. */
+  supportedExecutionModes?: Scope extends "internal"
+    ? readonly [WorkerExecutionMode] | readonly ["worker-turn", "remote-exec"]
+    : readonly [WorkerExecutionMode];
   /**
    * Provision before preparing an installation when the lease transport decides whether an
    * installation is needed. Defaults to false so SSH providers retain prepare-before-allocation.
diff --git a/src/plugins/plugin-registration.types.ts b/src/plugins/plugin-registration.types.ts
index a872df149e49..1dc4df6b6560 100644
--- a/src/plugins/plugin-registration.types.ts
+++ b/src/plugins/plugin-registration.types.ts
@@ -226,6 +226,7 @@ type OpenClawPluginNodeInvokePolicyApprovalRuntime = {
     toolCallId?: string;
     agentId?: string;
     sessionKey?: string;
+    allowedDecisions?: readonly OpenClawPluginNodeInvokeApprovalDecision[];
     timeoutMs?: number;
   }) => Promise<{
     id?: string;
diff --git a/src/plugins/runtime/types.ts b/src/plugins/runtime/types.ts
index 49d449c4a650..44692a7d7455 100644
--- a/src/plugins/runtime/types.ts
+++ b/src/plugins/runtime/types.ts
@@ -144,7 +144,10 @@ export type PluginRuntime = PluginRuntimeCore & {
     invoke: (params: RuntimeNodeInvokeParams) => Promise<unknown>;
     /** Open a connection-scoped binary node command inside the trusted Gateway runtime. */
     openDuplex: (
-      params: RuntimeNodeInvokeParams & { maxMessageBytes?: number },
+      params: RuntimeNodeInvokeParams & {
+        maxMessageBytes?: number;
+        maxOutstandingDeliveryBytes?: number;
+      },
     ) => Promise<RuntimeNodeDuplexChannel>;
   };
   sandbox: {
diff --git a/src/plugins/types.node-host.ts b/src/plugins/types.node-host.ts
index 0a69c4dd300b..14107aa9c679 100644
--- a/src/plugins/types.node-host.ts
+++ b/src/plugins/types.node-host.ts
@@ -26,6 +26,14 @@ export type OpenClawPluginNodeHostCommandContext = {
   sessionKey?: string;
   /** Aborts when the Gateway cancels this specific node-host invocation. */
   signal?: AbortSignal;
+  /** Protect one exact node-owned placement workspace for this invocation's lifetime. */
+  acquireManagedWorkspace?: (request: {
+    workspaceDir: string;
+    environmentId: string;
+    sessionId: string;
+    ownerEpoch: number;
+    sessionKey: string;
+  }) => { workspaceDir: string; release: () => void };
 };
 
 type OpenClawPluginNodeHostCommandBase = {
diff --git a/src/shared/session-types.ts b/src/shared/session-types.ts
index fcee9becc6ca..e124711a3ca2 100644
--- a/src/shared/session-types.ts
+++ b/src/shared/session-types.ts
@@ -1,4 +1,5 @@
 import type {
+  GatewayAgentRuntime as ProtocolGatewayAgentRuntime,
   SessionCreatedActor,
   SessionsAssignOwnerParams,
   WorkerExecutionMode,
@@ -25,6 +26,7 @@ export type GatewayAgentRuntime = {
   fallback?: "openclaw" | "none";
   cloudPlacementSupported?: boolean;
   cloudPlacementExecutionMode?: WorkerExecutionMode;
+  devicePlacement?: ProtocolGatewayAgentRuntime["devicePlacement"];
   devicePlacementSupported?: boolean;
   source:
     | "env"
diff --git a/test/e2e/qa-lab/runtime/codex-node-exec-server.e2e.test.ts b/test/e2e/qa-lab/runtime/codex-node-exec-server.e2e.test.ts
new file mode 100644
index 000000000000..1e437a445e17
--- /dev/null
+++ b/test/e2e/qa-lab/runtime/codex-node-exec-server.e2e.test.ts
@@ -0,0 +1,834 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import { createServer, type ServerResponse } from "node:http";
+import path from "node:path";
+import { promisify } from "node:util";
+import { GatewayClient } from "openclaw/plugin-sdk/gateway-runtime";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { startQaGatewayChild, startQaMockOpenAiServer } from "../../../../extensions/qa-lab/api.js";
+import {
+  GATEWAY_CLIENT_CAPS,
+  GATEWAY_CLIENT_MODES,
+  GATEWAY_CLIENT_NAMES,
+} from "../../../../packages/gateway-protocol/src/client-info.js";
+import type { OpenClawConfig } from "../../../../src/config/types.openclaw.js";
+import { useAutoCleanupTempDirTracker } from "../../../helpers/temp-dir.js";
+import {
+  approvePairing,
+  createChildEnv,
+  processIsAlive,
+  readNode,
+  startNodeProcess,
+  stopChild,
+  type CapturedChild,
+  type GatewayHandle,
+} from "./gateway-node-mcp.test-support.js";
+import {
+  closeWireServer,
+  createPublishedWireWorkspace,
+  type PublishedWireWorkspace,
+} from "./paired-node-worker-wire-fixture.js";
+
+const execFileAsync = promisify(execFile);
+const tempDirs = useAutoCleanupTempDirTracker(afterEach);
+const COMMAND = "codex.exec-server.stdio.v1";
+const MODEL = "mock-openai/gpt-5.6-luna";
+const SESSION_KEY = "agent:qa:codex-node-exec-server-proof";
+const SUCCESS_MARKER = "CODEX_NODE_EXEC_SUCCESS_PROOF";
+const DISCONNECT_MARKER = "CODEX_NODE_EXEC_DISCONNECT_PROOF";
+const RECOVERY_MARKER = "CODEX_NODE_EXEC_FRESH_ATTEMPT_PROOF";
+const REQUEST_TIMEOUT_MS = 120_000;
+const WAIT_OPTIONS = { timeout: 60_000, interval: 100 };
+
+type ProofScenario = "success" | "disconnect" | "recovery";
+type PendingPluginApproval = {
+  id: string;
+  request?: { pluginId?: string; allowedDecisions?: string[]; title?: string };
+};
+type ProofProvider = {
+  readonly baseUrl: string;
+  readonly httpHits: number;
+  readonly nativeExecCalls: number;
+  readonly observations: readonly string[];
+  readonly visibleTools: ReadonlySet<string>;
+  stop: () => Promise<void>;
+};
+
+function writeProofEvent(response: ServerResponse, event: Record<string, unknown>): void {
+  response.write(`data: ${JSON.stringify(event)}\n\n`);
+}
+
+function finishProofResponse(response: ServerResponse, item: Record<string, unknown>): void {
+  const responseId = `resp_codex_node_${randomUUID()}`;
+  response.writeHead(200, {
+    "content-type": "text/event-stream",
+    "cache-control": "no-store",
+    connection: "keep-alive",
+  });
+  writeProofEvent(response, { type: "response.created", response: { id: responseId } });
+  writeProofEvent(response, { type: "response.output_item.done", item });
+  writeProofEvent(response, {
+    type: "response.completed",
+    response: {
+      id: responseId,
+      status: "completed",
+      output: [item],
+      usage: {
+        input_tokens: 32,
+        input_tokens_details: null,
+        output_tokens: 16,
+        output_tokens_details: null,
+        total_tokens: 48,
+      },
+    },
+  });
+  response.end("data: [DONE]\n\n");
+}
+
+function readProofScenario(body: Record<string, unknown>): ProofScenario | undefined {
+  const input = Array.isArray(body.input) ? body.input : [];
+  for (const entry of input.toReversed()) {
+    if (!entry || typeof entry !== "object" || !("role" in entry) || entry.role !== "user") {
+      continue;
+    }
+    const userText = JSON.stringify(entry);
+    if (userText.includes(RECOVERY_MARKER)) {
+      return "recovery";
+    }
+    if (userText.includes(DISCONNECT_MARKER)) {
+      return "disconnect";
+    }
+    if (userText.includes(SUCCESS_MARKER)) {
+      return "success";
+    }
+  }
+  return undefined;
+}
+
+function proofShellCommand(params: {
+  scenario: ProofScenario;
+  baseUrl: string;
+  nodeHome: string;
+}): string {
+  const script =
+    params.scenario === "disconnect"
+      ? [
+          'const fs=require("node:fs");',
+          'fs.writeFileSync("codex-node-disconnect.json",JSON.stringify({pid:process.pid}));',
+          "setInterval(()=>{},1000);",
+        ].join("")
+      : [
+          'const fs=require("node:fs");',
+          `fetch(${JSON.stringify(`${params.baseUrl}/proof-http`)})`,
+          ".then(async response=>{",
+          "const evidence={",
+          "openaiKeyPresent:Boolean(process.env.OPENAI_API_KEY),",
+          "anthropicKeyPresent:Boolean(process.env.ANTHROPIC_API_KEY),",
+          "forgeTokenPresent:Boolean(process.env.GITHUB_TOKEN||process.env.GH_TOKEN),",
+          "cloudKeyPresent:Boolean(process.env.AWS_ACCESS_KEY_ID),",
+          "gatewayTokenPresent:Boolean(process.env.OPENCLAW_GATEWAY_TOKEN),",
+          "runtimeInjectionPresent:Boolean(process.env.NODE_OPTIONS),",
+          "ordinary:process.env.NODE_ENV||null,",
+          `privateHome:process.env.HOME!==${JSON.stringify(params.nodeHome)},`,
+          'privateCodexHome:Boolean(process.env.CODEX_HOME&&process.env.CODEX_HOME.startsWith(process.env.HOME+"/")),',
+          "http:await response.text(),pid:process.pid};",
+          `fs.writeFileSync(${JSON.stringify(params.scenario === "recovery" ? "codex-node-recovery.json" : "codex-node-proof.json")},JSON.stringify(evidence));`,
+          `console.log(${JSON.stringify(params.scenario === "recovery" ? "CODEX_NODE_FRESH_ATTEMPT_OK" : "CODEX_NODE_PROCESS_OK")});`,
+          "}).catch(error=>{console.error(error.message);process.exitCode=1});",
+        ].join("");
+  return `node -e ${JSON.stringify(script)}`;
+}
+
+async function startProofProvider(nodeHome: string): Promise<ProofProvider> {
+  const mock = await startQaMockOpenAiServer({ host: "127.0.0.1", port: 0 });
+  let httpHits = 0;
+  let nativeExecCalls = 0;
+  const observations: string[] = [];
+  const visibleTools = new Set<string>();
+  let baseUrl = "";
+  const server = createServer((request, response) => {
+    void (async () => {
+      if (request.method === "GET" && request.url === "/proof-http") {
+        httpHits += 1;
+        response.writeHead(200, { "content-type": "text/plain" });
+        response.end("CODEX_NODE_HTTP_OK");
+        return;
+      }
+
+      const chunks: Buffer[] = [];
+      for await (const chunk of request) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array));
+      }
+      const raw = Buffer.concat(chunks);
+      if (request.method === "POST" && request.url === "/v1/responses") {
+        const body = JSON.parse(raw.toString("utf8")) as Record<string, unknown>;
+        for (const tool of Array.isArray(body.tools) ? body.tools : []) {
+          if (tool && typeof tool === "object" && "name" in tool && typeof tool.name === "string") {
+            visibleTools.add(tool.name);
+          }
+        }
+        const scenario = readProofScenario(body);
+        if (scenario) {
+          const callId = `call_codex_node_${scenario}`;
+          const completed = (Array.isArray(body.input) ? body.input : []).some(
+            (entry) =>
+              entry &&
+              typeof entry === "object" &&
+              "type" in entry &&
+              entry.type === "function_call_output" &&
+              "call_id" in entry &&
+              entry.call_id === callId,
+          );
+          observations.push(`${scenario}:${completed ? "completed" : "native-call"}`);
+          if (observations.length > 16) {
+            observations.shift();
+          }
+          if (completed) {
+            finishProofResponse(response, {
+              type: "message",
+              role: "assistant",
+              id: `msg_codex_node_${scenario}`,
+              content: [{ type: "output_text", text: `CODEX_NODE_${scenario.toUpperCase()}_OK` }],
+            });
+            return;
+          }
+          nativeExecCalls += 1;
+          finishProofResponse(response, {
+            type: "function_call",
+            call_id: callId,
+            name: "exec_command",
+            arguments: JSON.stringify({
+              cmd: proofShellCommand({ scenario, baseUrl, nodeHome }),
+              yield_time_ms: scenario === "disconnect" ? 10_000 : 30_000,
+              max_output_tokens: 1_000,
+            }),
+          });
+          return;
+        }
+        observations.push("unmatched");
+        if (observations.length > 16) {
+          observations.shift();
+        }
+      }
+
+      const forwarded = await fetch(`${mock.baseUrl}${request.url ?? "/"}`, {
+        method: request.method,
+        ...(raw.byteLength ? { body: raw } : {}),
+        headers: { "content-type": request.headers["content-type"] ?? "application/json" },
+      });
+      response.writeHead(forwarded.status, Object.fromEntries(forwarded.headers));
+      response.end(Buffer.from(await forwarded.arrayBuffer()));
+    })().catch((error: unknown) => {
+      if (!response.headersSent) {
+        response.writeHead(500, { "content-type": "text/plain" });
+      }
+      response.end(error instanceof Error ? error.message : "proof provider failed");
+    });
+  });
+
+  try {
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("Codex paired-node proof provider did not bind");
+    }
+    baseUrl = `http://127.0.0.1:${address.port}`;
+    return {
+      baseUrl,
+      get httpHits() {
+        return httpHits;
+      },
+      get nativeExecCalls() {
+        return nativeExecCalls;
+      },
+      observations,
+      visibleTools,
+      async stop() {
+        const cleanup = await Promise.allSettled([closeWireServer(server), mock.stop()]);
+        const failures = cleanup.flatMap((result) =>
+          result.status === "rejected" ? [result.reason] : [],
+        );
+        if (failures.length) {
+          throw new AggregateError(failures, "Codex proof provider cleanup failed");
+        }
+      },
+    };
+  } catch (error) {
+    server.closeAllConnections();
+    server.close();
+    await mock.stop();
+    throw error;
+  }
+}
+
+async function connectApprovalReviewer(gateway: GatewayHandle): Promise<GatewayClient> {
+  return await new Promise<GatewayClient>((resolve, reject) => {
+    let settled = false;
+    const finish = (error?: Error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      if (error) {
+        client.stop();
+        reject(error);
+      } else {
+        resolve(client);
+      }
+    };
+    const timeout = setTimeout(
+      () => finish(new Error("Codex node approval reviewer connection timed out")),
+      REQUEST_TIMEOUT_MS,
+    );
+    timeout.unref();
+    const client = new GatewayClient({
+      url: gateway.wsUrl,
+      token: gateway.token,
+      role: "operator",
+      clientName: GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT,
+      clientDisplayName: "Codex paired-node approval reviewer",
+      mode: GATEWAY_CLIENT_MODES.BACKEND,
+      scopes: ["operator.admin", "operator.approvals", "operator.pairing", "operator.write"],
+      caps: [GATEWAY_CLIENT_CAPS.PLUGIN_APPROVALS],
+      deviceIdentity: null,
+      requestTimeoutMs: REQUEST_TIMEOUT_MS,
+      onHelloOk: () => finish(),
+      onConnectError: (error) => finish(error),
+      onClose: (code, reason) => finish(new Error(`approval reviewer closed (${code}): ${reason}`)),
+    });
+    client.start();
+  });
+}
+
+async function resolveNextApproval(
+  reviewer: GatewayClient,
+  decision: "allow-once" | "deny",
+  context: { gateway: GatewayHandle; runId: string },
+): Promise<PendingPluginApproval> {
+  let pending: PendingPluginApproval;
+  try {
+    pending = await vi.waitFor(
+      async () => {
+        const approvals = await reviewer.request<PendingPluginApproval[]>(
+          "plugin.approval.list",
+          {},
+        );
+        const candidate = approvals.find((approval) => approval.request?.pluginId === "codex");
+        expect(candidate, "expected a pending Codex paired-node approval").toBeDefined();
+        return candidate!;
+      },
+      { timeout: 15_000, interval: 100 },
+    );
+  } catch (error) {
+    const [terminal, approvals] = await Promise.allSettled([
+      reviewer.request<{ status?: string; error?: string }>(
+        "agent.wait",
+        { runId: context.runId, timeoutMs: 1_000 },
+        { timeoutMs: 2_000 },
+      ),
+      reviewer.request<PendingPluginApproval[]>("plugin.approval.list", {}),
+    ]);
+    const details = {
+      runId: context.runId,
+      turn:
+        terminal.status === "fulfilled"
+          ? { status: terminal.value.status, error: terminal.value.error?.slice(0, 512) }
+          : { status: "unavailable" },
+      approvals:
+        approvals.status === "fulfilled"
+          ? approvals.value.map((approval) => ({
+              pluginId: approval.request?.pluginId,
+              title: approval.request?.title,
+              decisions: approval.request?.allowedDecisions,
+            }))
+          : "unavailable",
+    };
+    throw new Error(
+      `Codex paired-node approval did not become pending: ${JSON.stringify(details)}\n${context.gateway.logs().slice(-6_000)}`,
+      { cause: error },
+    );
+  }
+  expect(pending.request).toMatchObject({
+    pluginId: "codex",
+    title: "Run Codex execution on paired device",
+    allowedDecisions: ["allow-once", "deny"],
+  });
+  await reviewer.request("plugin.approval.resolve", { id: pending.id, decision });
+  return pending;
+}
+
+async function readRemoteEvidence<T>(filePath: string): Promise<T> {
+  return JSON.parse(await fs.readFile(filePath, "utf8")) as T;
+}
+
+async function nodeChildCommands(nodePid: number): Promise<string[]> {
+  const { stdout } = await execFileAsync("ps", ["-ax", "-o", "ppid=", "-o", "command="], {
+    encoding: "utf8",
+  });
+  return stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith(`${nodePid} `))
+    .map((line) => line.slice(String(nodePid).length).trim());
+}
+
+async function startTurn(reviewer: GatewayClient, marker: string): Promise<{ runId: string }> {
+  const runId = `codex-node-proof-${randomUUID()}`;
+  const started = await reviewer.request<{ runId?: string; status?: string }>("chat.send", {
+    sessionKey: SESSION_KEY,
+    message: marker,
+    deliver: false,
+    idempotencyKey: runId,
+  });
+  expect(started).toMatchObject({ runId, status: "started" });
+  return { runId };
+}
+
+async function expectSuccessfulTurn(params: {
+  reviewer: GatewayClient;
+  gateway: GatewayHandle;
+  node: CapturedChild;
+  provider: ProofProvider;
+  runId: string;
+}): Promise<void> {
+  const outcome = await params.reviewer.request<{ status?: string; error?: string }>(
+    "agent.wait",
+    { runId: params.runId, timeoutMs: REQUEST_TIMEOUT_MS },
+    { timeoutMs: REQUEST_TIMEOUT_MS + 5_000 },
+  );
+  if (outcome.status !== "ok") {
+    throw new Error(
+      `Codex paired-node turn failed: ${JSON.stringify({
+        runId: params.runId,
+        status: outcome.status,
+        error: outcome.error?.slice(0, 512),
+        nativeExecCalls: params.provider.nativeExecCalls,
+        httpHits: params.provider.httpHits,
+        observations: params.provider.observations,
+      })}\nGateway logs:\n${params.gateway.logs().slice(-6_000)}\nNode logs:\n${params.node.logs().slice(-6_000)}`,
+    );
+  }
+}
+
+describe("Codex paired-device exec-server carrier", () => {
+  it(
+    "keeps approved native execution on the real node, reconciles files, and never resumes a disconnect",
+    { timeout: 360_000 },
+    async () => {
+      const root = tempDirs.make("openclaw-codex-node-exec-server-");
+      const nodeRoot = path.join(root, "node");
+      const nodeHome = path.join(nodeRoot, "home");
+      const nodeState = path.join(nodeRoot, "state");
+      const nodeTmp = path.join(nodeRoot, "tmp");
+      const nodeConfigPath = path.join(nodeRoot, "openclaw.json");
+      await Promise.all(
+        [nodeHome, nodeState, nodeTmp].map(async (dir) => await fs.mkdir(dir, { recursive: true })),
+      );
+
+      let provider: ProofProvider | undefined;
+      let published: PublishedWireWorkspace | undefined;
+      let gateway: GatewayHandle | undefined;
+      let requester: GatewayClient | undefined;
+      let reviewer: GatewayClient | undefined;
+      let node: CapturedChild | undefined;
+
+      try {
+        provider = await startProofProvider(nodeHome);
+        published = await createPublishedWireWorkspace(path.join(root, "workspace"));
+        gateway = await startQaGatewayChild({
+          repoRoot: process.cwd(),
+          command: {
+            executablePath: process.execPath,
+            argsPrefix: ["dist/index.js"],
+            cwd: process.cwd(),
+            usePackagedPlugins: true,
+          },
+          transportBaseUrl: "http://127.0.0.1",
+          providerMode: "mock-openai",
+          providerBaseUrl: `${provider.baseUrl}/v1`,
+          primaryModel: MODEL,
+          alternateModel: MODEL,
+          forcedRuntime: "codex",
+          enabledPluginIds: ["codex"],
+          controlUiEnabled: false,
+          runtimeEnvPatch: {
+            OPENAI_API_KEY: "codex-node-gateway-fake-canary",
+            GITHUB_TOKEN: "codex-node-gateway-fake-forge-canary",
+            NODE_ENV: "ordinary-node-process-value",
+          },
+          mutateConfig: (config) => ({
+            ...config,
+            gateway: {
+              ...config.gateway,
+              nodes: {
+                ...config.gateway?.nodes,
+                commands: { allow: [COMMAND] },
+                pairing: {
+                  ...config.gateway?.nodes?.pairing,
+                  autoApproveLocal: false,
+                  sshVerify: false,
+                },
+              },
+            },
+            agents: {
+              ...config.agents,
+              defaults: {
+                ...config.agents?.defaults,
+                models: {
+                  ...config.agents?.defaults?.models,
+                  "openai/gpt-5.6-luna": { agentRuntime: { id: "codex" } },
+                },
+              },
+            },
+            nodeHost: { ...config.nodeHost, workerRuns: { enabled: true } },
+          }),
+        });
+        requester = await connectApprovalReviewer(gateway);
+        reviewer = await connectApprovalReviewer(gateway);
+
+        const nodeConfig: OpenClawConfig = {
+          gateway: { mode: "local" },
+          plugins: { allow: ["codex"], entries: { codex: { enabled: false } } },
+          nodeHost: { workerRuns: { enabled: true }, skills: { enabled: false } },
+        };
+        await fs.writeFile(nodeConfigPath, `${JSON.stringify(nodeConfig)}\n`, { mode: 0o600 });
+        const nodeEnv = createChildEnv({
+          home: nodeHome,
+          tempDir: nodeTmp,
+          extra: {
+            OPENCLAW_HOME: nodeHome,
+            OPENCLAW_STATE_DIR: nodeState,
+            OPENCLAW_CONFIG_PATH: nodeConfigPath,
+            OPENCLAW_GATEWAY_TOKEN: gateway.token,
+            OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: "1",
+            NODE_ENV: "ordinary-node-process-value",
+            OPENAI_API_KEY: "codex-node-device-fake-canary",
+            ANTHROPIC_API_KEY: "codex-node-device-fake-anthropic-canary",
+            GITHUB_TOKEN: "codex-node-device-fake-forge-canary",
+            AWS_ACCESS_KEY_ID: "codex-node-device-fake-cloud-canary",
+          },
+        });
+        const gatewayPort = Number(new URL(gateway.baseUrl).port);
+        node = startNodeProcess(gatewayPort, nodeEnv);
+        const nodeId = await approvePairing(gateway, "device");
+        await stopChild(node);
+        node = startNodeProcess(gatewayPort, nodeEnv);
+        await approvePairing(gateway, "node", nodeId);
+        await vi.waitFor(async () => {
+          const approved = (await readNode(gateway!, nodeId)) as
+            | {
+                connected?: boolean;
+                approvalState?: string;
+                commands?: string[];
+                sessionHost?: boolean;
+              }
+            | undefined;
+          expect(approved).toMatchObject({
+            connected: true,
+            approvalState: "approved",
+            sessionHost: true,
+          });
+          expect(approved?.commands).not.toContain(COMMAND);
+        }, WAIT_OPTIONS);
+
+        await gateway.call("sessions.create", {
+          key: SESSION_KEY,
+          agentId: "qa",
+          model: "openai/gpt-5.6-luna",
+          worktree: true,
+          worktreeName: "codex-node-exec-proof",
+          worktreeBaseRef: "main",
+          cwd: published.source,
+        });
+        const localSession = (await gateway.call("sessions.describe", { key: SESSION_KEY })) as {
+          session?: {
+            execCwd?: string;
+            spawnedCwd?: string;
+            placement?: Record<string, unknown>;
+          };
+        };
+        const localWorkspace = localSession.session?.execCwd ?? localSession.session?.spawnedCwd;
+        expect(localWorkspace).toBeTruthy();
+
+        await vi.waitFor(async () => {
+          const inventory = await reviewer!.request<{
+            environments?: Array<{
+              id?: string;
+              status?: string;
+              sessionHost?: boolean;
+              workerSlots?: { total: number; available: number };
+              invocableCommands?: string[];
+            }>;
+          }>("environments.list", {});
+          const environment = inventory.environments?.find(
+            (entry) => entry.id === `node:${nodeId}`,
+          );
+          expect(environment).toMatchObject({ status: "available", sessionHost: true });
+          expect(environment?.workerSlots?.available).toBeGreaterThan(0);
+          expect(environment?.invocableCommands ?? []).not.toContain(COMMAND);
+        }, WAIT_OPTIONS);
+        const unapprovedNodePid = node.child.pid;
+        expect(unapprovedNodePid).toBeTruthy();
+        await expect(
+          gateway.call(
+            "sessions.dispatch",
+            { key: SESSION_KEY, deviceId: nodeId },
+            { timeoutMs: REQUEST_TIMEOUT_MS },
+          ),
+        ).rejects.toThrow(/codex\.exec-server\.stdio\.v1|enabled|approved|command/iu);
+        const rejectedSession = (await gateway.call("sessions.describe", { key: SESSION_KEY })) as {
+          session?: { placement?: Record<string, unknown> };
+        };
+        expect(rejectedSession.session?.placement).toEqual(localSession.session?.placement);
+        expect(
+          (await reviewer.request<PendingPluginApproval[]>("plugin.approval.list", {})).filter(
+            (approval) => approval.request?.pluginId === "codex",
+          ),
+        ).toEqual([]);
+        expect(
+          (await nodeChildCommands(unapprovedNodePid!)).filter((command) =>
+            /(?:^|\s)(?:worker|codex(?:\s+exec-server)?)(?:\s|$)/iu.test(command),
+          ),
+        ).toEqual([]);
+        expect(provider.nativeExecCalls).toBe(0);
+
+        nodeConfig.plugins!.entries!.codex!.enabled = true;
+        await fs.writeFile(nodeConfigPath, `${JSON.stringify(nodeConfig)}\n`, { mode: 0o600 });
+        await stopChild(node);
+        node = startNodeProcess(gatewayPort, nodeEnv);
+        await approvePairing(gateway, "node", nodeId);
+        await stopChild(node);
+        node = startNodeProcess(gatewayPort, nodeEnv);
+        await vi.waitFor(async () => {
+          const approved = (await readNode(gateway!, nodeId)) as
+            | {
+                connected?: boolean;
+                approvalState?: string;
+                commands?: string[];
+                sessionHost?: boolean;
+              }
+            | undefined;
+          expect(approved).toMatchObject({
+            connected: true,
+            approvalState: "approved",
+            sessionHost: true,
+          });
+          expect(approved?.commands).toContain(COMMAND);
+          const inventory = await reviewer!.request<{
+            environments?: Array<{ id?: string; invocableCommands?: string[] }>;
+          }>("environments.list", {});
+          expect(
+            inventory.environments?.find((entry) => entry.id === `node:${nodeId}`)
+              ?.invocableCommands,
+          ).toContain(COMMAND);
+        }, WAIT_OPTIONS);
+
+        const dispatched = (await gateway.call(
+          "sessions.dispatch",
+          { key: SESSION_KEY, deviceId: nodeId },
+          { timeoutMs: REQUEST_TIMEOUT_MS },
+        )) as { placement?: { state?: string; remoteWorkspaceDir?: string } };
+        expect(dispatched.placement).toMatchObject({ state: "active" });
+        const remoteWorkspace = dispatched.placement?.remoteWorkspaceDir;
+        expect(remoteWorkspace).toEqual(expect.any(String));
+
+        const denied = await startTurn(requester, SUCCESS_MARKER);
+        await resolveNextApproval(reviewer, "deny", { gateway, runId: denied.runId });
+        const deniedOutcome = await reviewer.request<{ status?: string; error?: unknown }>(
+          "agent.wait",
+          { runId: denied.runId, timeoutMs: REQUEST_TIMEOUT_MS },
+          { timeoutMs: REQUEST_TIMEOUT_MS + 5_000 },
+        );
+        expect(deniedOutcome).toMatchObject({ status: "error" });
+        expect(provider.nativeExecCalls).toBe(0);
+        await expect(
+          fs.access(path.join(remoteWorkspace!, "codex-node-proof.json")),
+        ).rejects.toThrow();
+
+        const allowed = await startTurn(requester, SUCCESS_MARKER);
+        await resolveNextApproval(reviewer, "allow-once", { gateway, runId: allowed.runId });
+        await expectSuccessfulTurn({ reviewer, gateway, node, provider, runId: allowed.runId });
+        expect(provider.visibleTools).toContain("exec_command");
+        expect(provider.httpHits).toBe(1);
+        const expectedEvidence = {
+          openaiKeyPresent: false,
+          anthropicKeyPresent: false,
+          forgeTokenPresent: false,
+          cloudKeyPresent: false,
+          gatewayTokenPresent: false,
+          runtimeInjectionPresent: false,
+          ordinary: "ordinary-node-process-value",
+          privateHome: true,
+          privateCodexHome: true,
+          http: "CODEX_NODE_HTTP_OK",
+        };
+        await vi.waitFor(async () => {
+          expect(
+            await readRemoteEvidence<Record<string, unknown>>(
+              path.join(localWorkspace!, "codex-node-proof.json"),
+            ),
+          ).toMatchObject(expectedEvidence);
+        }, WAIT_OPTIONS);
+        const nodePid = node.child.pid;
+        expect(nodePid).toBeTruthy();
+        const children = await nodeChildCommands(nodePid!);
+        expect(children.filter((command) => /(?:^|\s)worker(?:\s|$)/u.test(command))).toEqual([]);
+
+        const interrupted = await startTurn(requester, DISCONNECT_MARKER);
+        await resolveNextApproval(reviewer, "allow-once", { gateway, runId: interrupted.runId });
+        let interruptedProcess: number;
+        try {
+          interruptedProcess = await vi.waitFor(
+            async () => {
+              const evidence = await readRemoteEvidence<{ pid?: number }>(
+                path.join(remoteWorkspace!, "codex-node-disconnect.json"),
+              );
+              expect(evidence.pid).toEqual(expect.any(Number));
+              expect(processIsAlive(evidence.pid!)).toBe(true);
+              return evidence.pid!;
+            },
+            { timeout: 15_000, interval: 100 },
+          );
+        } catch (error) {
+          const terminal = await reviewer
+            .request<{ status?: string; error?: string }>(
+              "agent.wait",
+              { runId: interrupted.runId, timeoutMs: 1_000 },
+              { timeoutMs: 2_000 },
+            )
+            .catch(() => ({ status: "unavailable" }));
+          throw new Error(
+            `Codex disconnect process never started: ${JSON.stringify({
+              runId: interrupted.runId,
+              turn: {
+                status: terminal.status,
+                error: "error" in terminal ? terminal.error?.slice(0, 512) : undefined,
+              },
+              nativeExecCalls: provider.nativeExecCalls,
+              httpHits: provider.httpHits,
+              observations: provider.observations,
+              nativeExecAvailable: provider.visibleTools.has("exec_command"),
+            })}\n${gateway.logs().slice(-6_000)}`,
+            { cause: error },
+          );
+        }
+        const interruptedTerminal = reviewer.request<{ status?: string; error?: unknown }>(
+          "agent.wait",
+          { runId: interrupted.runId, timeoutMs: 12_000 },
+          { timeoutMs: 17_000 },
+        );
+        await stopChild(node);
+        node = undefined;
+        const interruptedOutcome = await interruptedTerminal;
+        expect(interruptedOutcome).toMatchObject({ status: "error" });
+        if (
+          typeof interruptedOutcome.error !== "string" ||
+          !/paired.*device disconnected.*fresh attempt/iu.test(interruptedOutcome.error)
+        ) {
+          throw new Error(
+            `Codex node disconnect omitted actionable guidance: ${JSON.stringify({
+              runId: interrupted.runId,
+              status: interruptedOutcome.status,
+              error:
+                typeof interruptedOutcome.error === "string"
+                  ? interruptedOutcome.error.slice(0, 1_000)
+                  : undefined,
+              observations: provider.observations,
+            })}\n${gateway.logs().slice(-6_000)}`,
+          );
+        }
+        expect(interruptedOutcome.error).toEqual(
+          expect.stringMatching(/paired.*device disconnected.*fresh attempt/iu),
+        );
+        await vi.waitFor(
+          () => expect(processIsAlive(interruptedProcess)).toBe(false),
+          WAIT_OPTIONS,
+        );
+        await vi.waitFor(async () => {
+          expect(await readNode(gateway!, nodeId)).toMatchObject({ connected: false });
+        }, WAIT_OPTIONS);
+
+        node = startNodeProcess(gatewayPort, nodeEnv);
+        await vi.waitFor(async () => {
+          const reconnected = (await readNode(gateway!, nodeId)) as
+            | {
+                connected?: boolean;
+                paired?: boolean;
+                approvalState?: string;
+                commands?: string[];
+                sessionHost?: boolean;
+              }
+            | undefined;
+          expect(reconnected).toMatchObject({
+            connected: true,
+            paired: true,
+            approvalState: "approved",
+            sessionHost: true,
+          });
+          expect(reconnected?.commands).toContain(COMMAND);
+        }, WAIT_OPTIONS);
+        const recovered = await startTurn(requester, RECOVERY_MARKER);
+        expect(recovered.runId).not.toBe(interrupted.runId);
+        await resolveNextApproval(reviewer, "allow-once", { gateway, runId: recovered.runId });
+        await expectSuccessfulTurn({ reviewer, gateway, node, provider, runId: recovered.runId });
+        await vi.waitFor(async () => {
+          expect(
+            await readRemoteEvidence<Record<string, unknown>>(
+              path.join(localWorkspace!, "codex-node-recovery.json"),
+            ),
+          ).toMatchObject(expectedEvidence);
+          expect(
+            await readRemoteEvidence<{ pid?: number }>(
+              path.join(localWorkspace!, "codex-node-disconnect.json"),
+            ),
+          ).toMatchObject({ pid: interruptedProcess });
+        }, WAIT_OPTIONS);
+        expect(provider.httpHits).toBe(2);
+        console.info(
+          JSON.stringify({
+            proof: "codex-paired-device-remote-exec",
+            gatewayUrl: gateway.baseUrl,
+            nodeId,
+            deniedRunId: denied.runId,
+            allowedRunId: allowed.runId,
+            interruptedRunId: interrupted.runId,
+            recoveredRunId: recovered.runId,
+            inferenceProvider: "deterministic mock",
+            realAppServer: true,
+            realExecServer: true,
+            httpHits: provider.httpHits,
+            credentialCanaries: "absent",
+            missingCommandRejectedBeforeProvision: true,
+            workerSlotsDoNotGrantCommandAuthority: true,
+            workspaceReconciled: true,
+            disconnectTerminal: true,
+            freshReconnect: true,
+            workerChildLaunched: false,
+          }),
+        );
+      } finally {
+        const connectionCleanup = await Promise.allSettled([
+          stopChild(node),
+          requester?.stopAndWait({ timeoutMs: 5_000 }) ?? Promise.resolve(),
+          reviewer?.stopAndWait({ timeoutMs: 5_000 }) ?? Promise.resolve(),
+        ]);
+        const resourceCleanup = await Promise.allSettled([
+          gateway?.stop() ?? Promise.resolve(),
+          published ? closeWireServer(published.server) : Promise.resolve(),
+          provider?.stop() ?? Promise.resolve(),
+        ]);
+        const failures = [...connectionCleanup, ...resourceCleanup].flatMap((result) =>
+          result.status === "rejected" ? [result.reason] : [],
+        );
+        if (failures.length) {
+          throw new AggregateError(failures, "Codex paired-node proof cleanup failed");
+        }
+      }
+    },
+  );
+});
diff --git a/ui/src/components/session-placement-move-dialog.ts b/ui/src/components/session-placement-move-dialog.ts
index 1489a69e3417..84d42cd022e8 100644
--- a/ui/src/components/session-placement-move-dialog.ts
+++ b/ui/src/components/session-placement-move-dialog.ts
@@ -23,6 +23,7 @@ type Options = {
   sessionLabel: string;
   activeRun: boolean;
   deviceDisabledReason?: string;
+  profileDisabledReason?: (profile: DraftCloudProfile) => string | undefined;
   loadCatalog: () => Promise<Catalog>;
 };
 
@@ -165,6 +166,7 @@ export function showSessionPlacementMoveDialog(
                                     selectedId: profileSelected ? profile.id : "",
                                     submitting: false,
                                     icon: icons.server,
+                                    profileDisabledReason: options.profileDisabledReason,
                                     onSelect: (profileId) => select({ kind: "profile", profileId }),
                                   })}
                                   ${profileSelected && machines.length > 0
diff --git a/ui/src/e2e/new-session-page.environment-metadata.e2e.test.ts b/ui/src/e2e/new-session-page.environment-metadata.e2e.test.ts
index e9851729331a..7906b2aadfff 100644
--- a/ui/src/e2e/new-session-page.environment-metadata.e2e.test.ts
+++ b/ui/src/e2e/new-session-page.environment-metadata.e2e.test.ts
@@ -16,7 +16,7 @@ const updateIssue = {
 };
 
 suite.define(() => {
-  it("offers paired devices only to models that use the embedded runtime", async () => {
+  it("offers paired devices to every model whose runtime explicitly supports them", async () => {
     const context = await suite.browser.newContext({
       locale: "en-US",
       serviceWorkers: "block",
@@ -35,6 +35,7 @@ suite.define(() => {
             id: "openclaw",
             cloudPlacementSupported: true,
             devicePlacementSupported: true,
+            devicePlacement: { requiredNodeCommands: [], consumesWorkerSlot: true },
             source: "model",
           },
         },
@@ -46,6 +47,22 @@ suite.define(() => {
           agentRuntime: {
             id: "codex",
             cloudPlacementSupported: true,
+            devicePlacementSupported: true,
+            devicePlacement: {
+              requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+              consumesWorkerSlot: false,
+            },
+            source: "model",
+          },
+        },
+        {
+          available: true,
+          id: "claude-opus-4-6",
+          name: "Claude Opus 4.6",
+          provider: "anthropic",
+          agentRuntime: {
+            id: "cloud-only",
+            cloudPlacementSupported: true,
             devicePlacementSupported: false,
             source: "model",
           },
@@ -60,7 +77,19 @@ suite.define(() => {
               label: "Build Mac",
               status: "available",
               sessionHost: true,
-              workerSlots: { total: 2, available: 2 },
+              workerSlots: { total: 2, available: 0 },
+              capabilities: ["codex.exec-server.stdio.v1"],
+              invocableCommands: ["codex.exec-server.stdio.v1"],
+            },
+            {
+              id: "node:restricted-mac",
+              type: "node",
+              label: "Restricted Mac",
+              status: "available",
+              sessionHost: true,
+              workerSlots: { total: 2, available: 1 },
+              capabilities: ["codex.exec-server.stdio.v1"],
+              invocableCommands: [],
             },
           ],
           profiles: [],
@@ -75,30 +104,49 @@ suite.define(() => {
       const whereTrigger = page.locator("#new-session-where-trigger");
       const where = page.locator("wa-popover.new-session-page__where-popover");
       const device = where.locator('[data-value="device:build-mac"]');
+      const restrictedDevice = where.locator('[data-value="device:restricted-mac"]');
+      const modelSelect = page.locator('[data-chat-model-select="true"]');
 
       await whereTrigger.click();
       await device.waitFor();
-      expect(await device.isEnabled()).toBe(true);
-      expect(await device.textContent()).not.toContain("Needs the embedded runtime");
-      await captureDeviceRuntimeUiProof(page, "01-embedded-device-enabled.png");
+      expect(await device.isDisabled()).toBe(true);
+      expect(await device.textContent()).toContain("No worker slots are available");
+      expect(await restrictedDevice.isEnabled()).toBe(true);
+      await captureDeviceRuntimeUiProof(page, "01-embedded-device-capacity-gated.png");
       await page.keyboard.press("Escape");
 
-      await page.locator('[data-chat-model-select="true"]').click();
+      await modelSelect.click();
       await page.locator('[data-chat-model-option="openai/gpt-5.6-sol"]').click();
+      await expect.poll(() => modelSelect.textContent()).toContain("GPT-5.6 Sol");
+      await whereTrigger.click();
+      await expect.poll(() => device.isEnabled()).toBe(true);
+      await expect.poll(() => restrictedDevice.isDisabled()).toBe(true);
+      expect(await restrictedDevice.getAttribute("title")).toMatch(/enable|approv/i);
+      await captureDeviceRuntimeUiProof(
+        page,
+        "02-codex-zero-slot-enabled-denied-command-disabled.png",
+      );
+      await page.keyboard.press("Escape");
+
+      await modelSelect.click();
+      await page.locator('[data-chat-model-option="anthropic/claude-opus-4-6"]').click();
+      await expect.poll(() => modelSelect.textContent()).toContain("Claude Opus 4.6");
       await whereTrigger.click();
       await expect.poll(() => device.isDisabled()).toBe(true);
       await expect
         .poll(() => device.locator(".new-session-page__menu-fact").allTextContents())
-        .toEqual(["Needs the embedded runtime"]);
-      expect(await device.getAttribute("title")).toBe("Needs the embedded runtime");
-      await captureDeviceRuntimeUiProof(page, "02-codex-device-disabled.png");
+        .toEqual(["This runtime does not support paired devices"]);
+      expect(await device.getAttribute("title")).toBe(
+        "This runtime does not support paired devices",
+      );
+      await captureDeviceRuntimeUiProof(page, "03-cloud-only-device-disabled.png");
       await page.keyboard.press("Escape");
 
-      await page.locator('[data-chat-model-select="true"]').click();
+      await modelSelect.click();
       await page.locator('[data-chat-model-option="anthropic/claude-sonnet-4-6"]').click();
       await whereTrigger.click();
-      await expect.poll(() => device.isEnabled()).toBe(true);
-      expect(await device.textContent()).not.toContain("Needs the embedded runtime");
+      await expect.poll(() => device.isDisabled()).toBe(true);
+      await expect.poll(() => restrictedDevice.isEnabled()).toBe(true);
       expect(await gateway.getRequests("node.list")).toHaveLength(0);
     } finally {
       await context.close();
diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts
index 80d03301df7a..c33b6123ad13 100644
--- a/ui/src/i18n/locales/en.ts
+++ b/ui/src/i18n/locales/en.ts
@@ -817,7 +817,7 @@ export const en: TranslationMap = {
     cloudRuntimeUnsupported: "The {runtime} runtime does not support cloud workers.",
     cloudProfileRuntimeUnsupported:
       "The {runtime} runtime cannot use this cloud worker. Choose a compatible cloud worker or run locally.",
-    deviceRuntimeUnsupported: "Needs the embedded runtime",
+    deviceRuntimeUnsupported: "This runtime does not support paired devices",
     cloudRecoveryUnavailable:
       "Cloud workers are unavailable because this connection does not support task recovery. Reconnect or update the Gateway.",
     placementStartFailed: "The session was created, but runner startup failed: {error}",
diff --git a/ui/src/pages/chat/chat-pane-placement.runtime.ts b/ui/src/pages/chat/chat-pane-placement.runtime.ts
index b3e4fc8c6c81..2712fc5ac725 100644
--- a/ui/src/pages/chat/chat-pane-placement.runtime.ts
+++ b/ui/src/pages/chat/chat-pane-placement.runtime.ts
@@ -11,13 +11,20 @@ import { t } from "../../i18n/index.ts";
 import { readSessionMethodAccess } from "../../lib/session-method-access.ts";
 import { parseAgentSessionKey } from "../../lib/sessions/session-key.ts";
 import { requestPlaceCatalog } from "../new-session/cloud-target.ts";
-import { projectDevicePlacements } from "../new-session/device-placement.ts";
+import {
+  projectDevicePlacements,
+  type DevicePlacementRequirement,
+} from "../new-session/device-placement.ts";
 
-async function loadPlacementMoveCatalog(client: GatewayBrowserClient, includeProfiles: boolean) {
+async function loadPlacementMoveCatalog(
+  client: GatewayBrowserClient,
+  includeProfiles: boolean,
+  requirement?: DevicePlacementRequirement,
+) {
   const catalog = await requestPlaceCatalog(client);
   return {
     profiles: includeProfiles ? catalog.profiles : [],
-    devices: projectDevicePlacements(catalog.environments),
+    devices: projectDevicePlacements(catalog.environments, requirement),
   };
 }
 
@@ -68,17 +75,27 @@ export async function moveChatPanePlacement(params: {
   } else {
     const { showSessionPlacementMoveDialog } =
       await import("../../components/session-placement-move-dialog.ts");
+    const runtime = params.row.agentRuntime;
     target = await showSessionPlacementMoveDialog({
       sessionLabel: params.row.label || params.row.key,
       activeRun: params.row.hasActiveRun === true,
       deviceDisabledReason:
-        params.row.agentRuntime?.devicePlacementSupported === false
-          ? t("newSession.deviceRuntimeUnsupported")
-          : undefined,
+        runtime && !runtime.devicePlacement ? t("newSession.deviceRuntimeUnsupported") : undefined,
+      profileDisabledReason: (profile) => {
+        if (runtime?.cloudPlacementSupported === false) {
+          return t("newSession.cloudRuntimeUnsupported", { runtime: runtime.id });
+        }
+        return runtime?.cloudPlacementExecutionMode &&
+          profile.executionMode &&
+          profile.executionMode !== runtime.cloudPlacementExecutionMode
+          ? t("newSession.cloudProfileRuntimeUnsupported", { runtime: runtime.id })
+          : undefined;
+      },
       loadCatalog: async () =>
         await loadPlacementMoveCatalog(
           client,
           hasOperatorAdminAccess(params.gatewaySnapshot.hello?.auth ?? null),
+          runtime?.devicePlacement,
         ),
     });
   }
diff --git a/ui/src/pages/chat/chat-pane-placement.test.ts b/ui/src/pages/chat/chat-pane-placement.test.ts
index 1f14872ee5af..240e710f6c3a 100644
--- a/ui/src/pages/chat/chat-pane-placement.test.ts
+++ b/ui/src/pages/chat/chat-pane-placement.test.ts
@@ -350,6 +350,90 @@ describe("chat pane placement", () => {
     expect(refreshReplacement).toHaveBeenCalledWith("main");
   });
 
+  it("disables incompatible cloud execution modes while preserving compatible machine selection", async () => {
+    const request = vi.fn(async (method: string) => {
+      if (method === "environments.list") {
+        return {
+          profiles: [
+            {
+              id: "worker-only",
+              providerId: "crabbox",
+              executionMode: "worker-turn",
+            },
+            {
+              id: "remote-exec",
+              providerId: "crabbox",
+              executionMode: "remote-exec",
+              machines: [
+                { id: "standard", label: "Standard", default: true },
+                { id: "beast", label: "Beast" },
+              ],
+            },
+          ],
+          environments: [],
+        };
+      }
+      return { ok: true };
+    });
+    const { pane } = createTestChatPane({
+      client: { request } as unknown as GatewayBrowserClient,
+      sessions: {
+        refreshReplacement: vi.fn(async () => undefined),
+      } as unknown as SessionCapability,
+    });
+    pane.context.gateway.snapshot.hello = {
+      features: { methods: ["sessions.move"] },
+      auth: { role: "operator", scopes: ["operator.admin", "operator.write"] },
+    } as never;
+    const session = {
+      ...activePlacementSession(),
+      agentRuntime: {
+        id: "codex",
+        cloudPlacementSupported: true,
+        cloudPlacementExecutionMode: "remote-exec",
+        source: "model",
+      },
+    } satisfies GatewaySessionRow;
+
+    const moving = pane.moveHeaderPlacement(session);
+    try {
+      await vi.waitFor(() => {
+        expect(document.body.querySelector('[data-value="cloud:worker-only"]')).not.toBeNull();
+      });
+      const incompatible = document.body.querySelector<HTMLButtonElement>(
+        '[data-value="cloud:worker-only"]',
+      );
+      expect(incompatible?.disabled).toBe(true);
+      expect(incompatible?.title).toMatch(/compatible cloud worker|cannot use/i);
+      const compatible = document.body.querySelector<HTMLButtonElement>(
+        '[data-value="cloud:remote-exec"]',
+      );
+      expect(compatible?.disabled).toBe(false);
+      compatible?.click();
+      document.body.querySelector<HTMLButtonElement>('[data-value="machine:beast"]')?.click();
+      [...document.body.querySelectorAll<HTMLButtonElement>("button")]
+        .find((button) => button.textContent?.trim() === "Move session")
+        ?.click();
+      await moving;
+
+      expect(request).toHaveBeenCalledWith(
+        "sessions.move",
+        expect.objectContaining({
+          target: {
+            kind: "profile",
+            profileId: "remote-exec",
+            machineClass: "beast",
+          },
+        }),
+      );
+    } finally {
+      [...document.body.querySelectorAll<HTMLButtonElement>("button")]
+        .find((button) => button.textContent?.trim() === "Cancel")
+        ?.click();
+      await moving;
+    }
+  });
+
   it("cancels offline-device continuation without opening a picker or sending an RPC", async () => {
     const request = vi.fn(async () => ({ ok: true }));
     const { pane } = createTestChatPane({
@@ -462,7 +546,7 @@ describe("chat pane placement", () => {
     const session = {
       ...activePlacementSession(),
       agentRuntime: {
-        id: "codex",
+        id: "cloud-only",
         cloudPlacementSupported: true,
         devicePlacementSupported: false,
         source: "model",
@@ -477,8 +561,8 @@ describe("chat pane placement", () => {
       '[data-value="device:build-mac"]',
     );
     expect(device?.disabled).toBe(true);
-    expect(device?.textContent).toContain("Needs the embedded runtime");
-    expect(device?.title).toBe("Needs the embedded runtime");
+    expect(device?.textContent).toContain("This runtime does not support paired devices");
+    expect(device?.title).toBe("This runtime does not support paired devices");
     [...document.body.querySelectorAll<HTMLButtonElement>("button")]
       .find((button) => button.textContent?.trim() === "Cancel")
       ?.click();
@@ -488,7 +572,120 @@ describe("chat pane placement", () => {
     expect(request).not.toHaveBeenCalledWith("node.list", expect.anything());
   });
 
-  it("moves an embedded-runtime session to a paired device", async () => {
+  it.each([
+    { runtimeId: "openclaw", executionMode: "worker-turn" },
+    { runtimeId: "codex", executionMode: "remote-exec" },
+  ] as const)(
+    "moves a $runtimeId session to a supported paired device",
+    async ({ runtimeId, executionMode }) => {
+      const request = vi.fn(async (method: string) => {
+        if (method === "environments.list") {
+          return {
+            profiles: [],
+            environments: [
+              {
+                id: "node:build-mac",
+                type: "node",
+                label: "Build Mac",
+                status: "available",
+                sessionHost: true,
+                workerSlots: { total: 1, available: 1 },
+                invocableCommands: ["codex.exec-server.stdio.v1"],
+              },
+            ],
+          };
+        }
+        return { ok: true };
+      });
+      const refreshReplacement = vi.fn(async () => undefined);
+      const { pane } = createTestChatPane({
+        client: { request } as unknown as GatewayBrowserClient,
+        sessions: { refreshReplacement } as unknown as SessionCapability,
+      });
+      pane.context.gateway.snapshot.hello = {
+        features: { methods: ["sessions.move"] },
+        auth: { role: "operator", scopes: ["operator.admin", "operator.write"] },
+      } as never;
+      const session = {
+        ...activePlacementSession(),
+        agentRuntime: {
+          id: runtimeId,
+          cloudPlacementSupported: true,
+          cloudPlacementExecutionMode: executionMode,
+          devicePlacementSupported: true,
+          devicePlacement:
+            executionMode === "remote-exec"
+              ? {
+                  requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+                  consumesWorkerSlot: false,
+                }
+              : { requiredNodeCommands: [], consumesWorkerSlot: true },
+          source: "model",
+        },
+      } satisfies GatewaySessionRow;
+
+      const moving = pane.moveHeaderPlacement(session);
+      await vi.waitFor(() => {
+        expect(document.body.querySelector('[data-value="device:build-mac"]')).not.toBeNull();
+      });
+      document.body.querySelector<HTMLButtonElement>('[data-value="device:build-mac"]')?.click();
+      [...document.body.querySelectorAll<HTMLButtonElement>("button")]
+        .find((button) => button.textContent?.trim() === "Move session")
+        ?.click();
+      await moving;
+
+      expect(request).toHaveBeenCalledWith("sessions.move", {
+        key: session.key,
+        agentId: "main",
+        expected: {
+          generation: 1,
+          environmentId: "worker:one",
+          ownerEpoch: 1,
+        },
+        target: { kind: "device", deviceId: "build-mac" },
+      });
+      expect(refreshReplacement).toHaveBeenCalledWith("main");
+      expect(request).not.toHaveBeenCalledWith("node.list", expect.anything());
+    },
+  );
+
+  it.each([
+    {
+      name: "remote execution ignores saturated worker capacity when its command is enabled",
+      runtimeId: "codex",
+      executionMode: "remote-exec",
+      devicePlacement: {
+        requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+        consumesWorkerSlot: false,
+      },
+      availableSlots: 0,
+      invocableCommands: ["codex.exec-server.stdio.v1"],
+      disabled: false,
+    },
+    {
+      name: "worker execution remains disabled at capacity",
+      runtimeId: "openclaw",
+      executionMode: "worker-turn",
+      devicePlacement: { requiredNodeCommands: [], consumesWorkerSlot: true },
+      availableSlots: 0,
+      invocableCommands: [],
+      disabled: true,
+      reason: /worker slots/i,
+    },
+    {
+      name: "declared remote execution remains disabled without Gateway command authority",
+      runtimeId: "codex",
+      executionMode: "remote-exec",
+      devicePlacement: {
+        requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+        consumesWorkerSlot: false,
+      },
+      availableSlots: 1,
+      invocableCommands: [],
+      disabled: true,
+      reason: /enable|approv/i,
+    },
+  ] as const)("$name in the Move Session picker", async (scenario) => {
     const request = vi.fn(async (method: string) => {
       if (method === "environments.list") {
         return {
@@ -500,17 +697,20 @@ describe("chat pane placement", () => {
               label: "Build Mac",
               status: "available",
               sessionHost: true,
-              workerSlots: { total: 1, available: 1 },
+              workerSlots: { total: 1, available: scenario.availableSlots },
+              capabilities: ["codex.exec-server.stdio.v1"],
+              invocableCommands: scenario.invocableCommands,
             },
           ],
         };
       }
       return { ok: true };
     });
-    const refreshReplacement = vi.fn(async () => undefined);
     const { pane } = createTestChatPane({
       client: { request } as unknown as GatewayBrowserClient,
-      sessions: { refreshReplacement } as unknown as SessionCapability,
+      sessions: {
+        refreshReplacement: vi.fn(async () => undefined),
+      } as unknown as SessionCapability,
     });
     pane.context.gateway.snapshot.hello = {
       features: { methods: ["sessions.move"] },
@@ -519,35 +719,38 @@ describe("chat pane placement", () => {
     const session = {
       ...activePlacementSession(),
       agentRuntime: {
-        id: "openclaw",
+        id: scenario.runtimeId,
         cloudPlacementSupported: true,
+        cloudPlacementExecutionMode: scenario.executionMode,
         devicePlacementSupported: true,
+        devicePlacement: {
+          requiredNodeCommands: [...scenario.devicePlacement.requiredNodeCommands],
+          consumesWorkerSlot: scenario.devicePlacement.consumesWorkerSlot,
+        },
         source: "model",
       },
     } satisfies GatewaySessionRow;
 
     const moving = pane.moveHeaderPlacement(session);
-    await vi.waitFor(() => {
-      expect(document.body.querySelector('[data-value="device:build-mac"]')).not.toBeNull();
-    });
-    document.body.querySelector<HTMLButtonElement>('[data-value="device:build-mac"]')?.click();
-    [...document.body.querySelectorAll<HTMLButtonElement>("button")]
-      .find((button) => button.textContent?.trim() === "Move session")
-      ?.click();
-    await moving;
+    try {
+      await vi.waitFor(() => {
+        expect(document.body.querySelector('[data-value="device:build-mac"]')).not.toBeNull();
+      });
+      const device = document.body.querySelector<HTMLButtonElement>(
+        '[data-value="device:build-mac"]',
+      );
+      expect(device?.disabled).toBe(scenario.disabled);
+      if (scenario.reason !== undefined) {
+        expect(device?.title).toMatch(scenario.reason);
+      }
+    } finally {
+      [...document.body.querySelectorAll<HTMLButtonElement>("button")]
+        .find((button) => button.textContent?.trim() === "Cancel")
+        ?.click();
+      await moving;
+    }
 
-    expect(request).toHaveBeenCalledWith("sessions.move", {
-      key: session.key,
-      agentId: "main",
-      expected: {
-        generation: 1,
-        environmentId: "worker:one",
-        ownerEpoch: 1,
-      },
-      target: { kind: "device", deviceId: "build-mac" },
-    });
-    expect(refreshReplacement).toHaveBeenCalledWith("main");
-    expect(request).not.toHaveBeenCalledWith("node.list", expect.anything());
+    expect(request).not.toHaveBeenCalledWith("sessions.move", expect.anything());
   });
 
   it("does not reclaim when the operator cancels", async () => {
diff --git a/ui/src/pages/new-session/device-placement.test.ts b/ui/src/pages/new-session/device-placement.test.ts
index 93eda1d9b59d..e801e571545f 100644
--- a/ui/src/pages/new-session/device-placement.test.ts
+++ b/ui/src/pages/new-session/device-placement.test.ts
@@ -127,4 +127,56 @@ describe("device placement projection", () => {
       { deviceId: "unique", subtitle: undefined },
     ]);
   });
+
+  it.each([
+    {
+      name: "remote execution remains available when every worker slot is occupied",
+      requirement: {
+        requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+        consumesWorkerSlot: false,
+      },
+      environment: {
+        workerSlots: { total: 2, available: 0 },
+        invocableCommands: ["codex.exec-server.stdio.v1"],
+      },
+      selectable: true,
+    },
+    {
+      name: "worker turns remain unavailable when every worker slot is occupied",
+      requirement: { requiredNodeCommands: [], consumesWorkerSlot: true },
+      environment: { workerSlots: { total: 2, available: 0 } },
+      selectable: false,
+      reason: /worker slots/i,
+    },
+    {
+      name: "declaring a command does not grant Gateway invocation authority",
+      requirement: {
+        requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+        consumesWorkerSlot: false,
+      },
+      environment: {
+        capabilities: ["codex.exec-server.stdio.v1"],
+        invocableCommands: [],
+      },
+      selectable: false,
+      reason: /enable|approv/i,
+    },
+    {
+      name: "missing command authority fails closed even when worker slots are free",
+      requirement: {
+        requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+        consumesWorkerSlot: false,
+      },
+      environment: { invocableCommands: ["camera.snap"] },
+      selectable: false,
+      reason: /enable|approv/i,
+    },
+  ])("$name", ({ requirement, environment, selectable, reason }) => {
+    const [device] = projectDevicePlacements([node(environment)], requirement);
+
+    expect(device?.selectable).toBe(selectable);
+    if (reason) {
+      expect(device?.disabledReason).toMatch(reason);
+    }
+  });
 });
diff --git a/ui/src/pages/new-session/device-placement.ts b/ui/src/pages/new-session/device-placement.ts
index 25a37b7f4323..64597c9835db 100644
--- a/ui/src/pages/new-session/device-placement.ts
+++ b/ui/src/pages/new-session/device-placement.ts
@@ -12,7 +12,20 @@ export type DevicePlacementOption = Readonly<{
   disabledReason?: string;
 }>;
 
-function unavailableReason(environment: DraftEnvironment): string | undefined {
+export type DevicePlacementRequirement = Readonly<{
+  requiredNodeCommands: readonly string[];
+  consumesWorkerSlot: boolean;
+}>;
+
+const DEFAULT_DEVICE_PLACEMENT: DevicePlacementRequirement = {
+  requiredNodeCommands: [],
+  consumesWorkerSlot: true,
+};
+
+function unavailableReason(
+  environment: DraftEnvironment,
+  requirement: DevicePlacementRequirement,
+): string | undefined {
   const updateIssue = environment.issues?.find((issue) => issue.code === "update-required");
   if (updateIssue) {
     return t("newSession.nodeUpdateRequired", {
@@ -26,6 +39,15 @@ function unavailableReason(environment: DraftEnvironment): string | undefined {
   if (environment.sessionHost !== true) {
     return t("newSession.sessionHostingDisabled");
   }
+  const unavailableCommand = requirement.requiredNodeCommands.find(
+    (command) => !environment.invocableCommands?.includes(command),
+  );
+  if (unavailableCommand) {
+    return `${t("pluginsPage.enableAction")} ${unavailableCommand}: gateway.nodes.commands.allow.`;
+  }
+  if (!requirement.consumesWorkerSlot) {
+    return undefined;
+  }
   if (!environment.workerSlots) {
     return t("newSession.deviceCapacityUnavailable");
   }
@@ -35,6 +57,7 @@ function unavailableReason(environment: DraftEnvironment): string | undefined {
 /** One projection owns device presentation, restore eligibility, and submit eligibility. */
 export function projectDevicePlacements(
   environments: readonly DraftEnvironment[] | null,
+  requirement: DevicePlacementRequirement = DEFAULT_DEVICE_PLACEMENT,
 ): DevicePlacementOption[] {
   const devices = (environments ?? [])
     .flatMap<DevicePlacementOption>((environment) => {
@@ -45,7 +68,7 @@ export function projectDevicePlacements(
       if (!deviceId) {
         return [];
       }
-      const disabledReason = unavailableReason(environment);
+      const disabledReason = unavailableReason(environment, requirement);
       const facts = environmentMenuFacts(environment, {
         connected: environment.status === "available",
       });
@@ -85,6 +108,9 @@ export function projectDevicePlacements(
 export function findDevicePlacement(
   environments: readonly DraftEnvironment[] | null,
   deviceId: string,
+  requirement?: DevicePlacementRequirement,
 ): DevicePlacementOption | undefined {
-  return projectDevicePlacements(environments).find((device) => device.deviceId === deviceId);
+  return projectDevicePlacements(environments, requirement).find(
+    (device) => device.deviceId === deviceId,
+  );
 }
diff --git a/ui/src/pages/new-session/discovery.test.ts b/ui/src/pages/new-session/discovery.test.ts
index f1e31ae926c0..506d9e5672fd 100644
--- a/ui/src/pages/new-session/discovery.test.ts
+++ b/ui/src/pages/new-session/discovery.test.ts
@@ -101,6 +101,28 @@ describe("readDraftEnvironments", () => {
     ).toEqual([issue]);
   });
 
+  it("normalizes bounded invocable commands separately from declared capabilities", () => {
+    expect(
+      readDraftEnvironments([
+        {
+          id: "node:runner",
+          type: "node",
+          status: "available",
+          capabilities: ["codex.exec-server.stdio.v1", "camera.snap"],
+          invocableCommands: [" z.command ", "camera.snap", "camera.snap", "x".repeat(129), ""],
+        },
+      ]),
+    ).toEqual([
+      {
+        id: "node:runner",
+        type: "node",
+        status: "available",
+        capabilities: ["codex.exec-server.stdio.v1", "camera.snap"],
+        invocableCommands: ["camera.snap", "z.command"],
+      },
+    ]);
+  });
+
   it("keeps the closed environment types while rejecting malformed entries", () => {
     expect(
       readDraftEnvironments([
diff --git a/ui/src/pages/new-session/discovery.ts b/ui/src/pages/new-session/discovery.ts
index 8778e2e45d84..c41168dc57eb 100644
--- a/ui/src/pages/new-session/discovery.ts
+++ b/ui/src/pages/new-session/discovery.ts
@@ -1,6 +1,9 @@
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
-import { normalizeArrayBackedTrimmedStringList } from "@openclaw/normalization-core/string-normalization";
+import {
+  normalizeArrayBackedTrimmedStringList,
+  normalizeSortedUniqueTrimmedStringList,
+} from "@openclaw/normalization-core/string-normalization";
 import type {
   EnvironmentStatus,
   RuntimeTargetIssue,
@@ -52,6 +55,7 @@ export type DraftEnvironment = {
   lastSeenReason?: string;
   trust?: "persistent" | "disposable";
   capabilities?: string[];
+  invocableCommands?: string[];
   issues?: RuntimeTargetIssue[];
 };
 
@@ -194,6 +198,7 @@ export function readDraftEnvironments(value: unknown): DraftEnvironment[] {
         lastSeenReason?: unknown;
         trust?: unknown;
         capabilities?: unknown;
+        invocableCommands?: unknown;
         issues?: unknown;
       };
       const id = normalizeOptionalString(environment.id);
@@ -213,6 +218,11 @@ export function readDraftEnvironments(value: unknown): DraftEnvironment[] {
           ? environment.trust
           : undefined;
       const capabilities = normalizeArrayBackedTrimmedStringList(environment.capabilities);
+      const invocableCommands = Array.isArray(environment.invocableCommands)
+        ? normalizeSortedUniqueTrimmedStringList(environment.invocableCommands)
+            .filter((command) => command.length <= 128)
+            .slice(0, 128)
+        : undefined;
       const lastConnectedAtMs = normalizeTimestamp(environment.lastConnectedAtMs);
       const lastDisconnectedAtMs = normalizeTimestamp(environment.lastDisconnectedAtMs);
       const lastSeenAtMs = normalizeTimestamp(environment.lastSeenAtMs);
@@ -236,6 +246,7 @@ export function readDraftEnvironments(value: unknown): DraftEnvironment[] {
           ...(lastSeenReason ? { lastSeenReason } : {}),
           ...(trust ? { trust } : {}),
           ...(capabilities ? { capabilities } : {}),
+          ...(invocableCommands ? { invocableCommands } : {}),
           ...(issues ? { issues } : {}),
         },
       ];
diff --git a/ui/src/pages/new-session/draft-place-state.ts b/ui/src/pages/new-session/draft-place-state.ts
index d1f18f047e70..30175c753779 100644
--- a/ui/src/pages/new-session/draft-place-state.ts
+++ b/ui/src/pages/new-session/draft-place-state.ts
@@ -165,25 +165,34 @@ export class DraftPlaceState {
     return this.agents().find((agent) => normalizeAgentId(agent.id) === agentId);
   }
 
+  devicePlacementRequirement() {
+    return this.modelControl.resolveAgentRuntime({
+      agent: this.selectedAgent(),
+      context: this.read().context,
+    })?.devicePlacement;
+  }
+
   devices() {
-    return projectDevicePlacements(this.gateway.environments);
+    return projectDevicePlacements(this.gateway.environments, this.devicePlacementRequirement());
+  }
+
+  private findDevice(deviceId: string) {
+    return findDevicePlacement(
+      this.gateway.environments,
+      deviceId,
+      this.devicePlacementRequirement(),
+    );
   }
 
   devicePlacementReady(): boolean {
-    return (
-      !this.deviceIdValue ||
-      findDevicePlacement(this.gateway.environments, this.deviceIdValue)?.selectable === true
-    );
+    return !this.deviceIdValue || this.findDevice(this.deviceIdValue)?.selectable === true;
   }
 
   devicePlacementDisabledReason(): string | undefined {
     if (!this.deviceIdValue) {
       return undefined;
     }
-    return (
-      findDevicePlacement(this.gateway.environments, this.deviceIdValue)?.disabledReason ??
-      t("newSession.nodeUnavailable")
-    );
+    return this.findDevice(this.deviceIdValue)?.disabledReason ?? t("newSession.nodeUnavailable");
   }
 
   isAdmin(): boolean {
@@ -498,7 +507,7 @@ export class DraftPlaceState {
     if (snapshot.submitting || snapshot.pendingPlacementSessionKey) {
       return;
     }
-    if (deviceId && findDevicePlacement(this.gateway.environments, deviceId)?.selectable !== true) {
+    if (deviceId && this.findDevice(deviceId)?.selectable !== true) {
       return;
     }
     if (deviceId === this.deviceIdValue && !this.cloudProfileIdValue) {
@@ -604,7 +613,7 @@ export class DraftPlaceState {
     }
 
     if (preferredWhere?.kind === "device" && this.gateway.cloudProfilesReady) {
-      const device = findDevicePlacement(this.gateway.environments, preferredWhere.id);
+      const device = this.findDevice(preferredWhere.id);
       this.deviceIdValue = device?.selectable === true ? preferredWhere.id : "";
       this.cloudProfileIdValue = "";
       this.repositoryState.forceWorktree(Boolean(this.deviceIdValue));
diff --git a/ui/src/pages/new-session/draft-submission-flow.test.ts b/ui/src/pages/new-session/draft-submission-flow.test.ts
index f175840ba6b3..9bd22844a1bf 100644
--- a/ui/src/pages/new-session/draft-submission-flow.test.ts
+++ b/ui/src/pages/new-session/draft-submission-flow.test.ts
@@ -320,7 +320,7 @@ describe("DraftSubmissionFlow submit gates", () => {
           workspaceGit: false,
           model: { primary: "openai/gpt-5.6-sol" },
           agentRuntime: {
-            id: "codex",
+            id: "cloud-only",
             cloudPlacementSupported: true,
             devicePlacementSupported: false,
             source: "model",
@@ -351,10 +351,12 @@ describe("DraftSubmissionFlow submit gates", () => {
 
     expect(fixture.flow.submitBlock()).toEqual({
       gate: "device-runtime",
-      reason: "Needs the embedded runtime",
+      reason: "This runtime does not support paired devices",
     });
     expect(fixture.flow.canSubmit()).toBe(false);
-    expect(fixture.flow.submitDisabledReason()).toBe("Needs the embedded runtime");
+    expect(fixture.flow.submitDisabledReason()).toBe(
+      "This runtime does not support paired devices",
+    );
     expect(fixture.request).not.toHaveBeenCalledWith("node.list", expect.anything());
   });
 });
diff --git a/ui/src/pages/new-session/model-control.test.ts b/ui/src/pages/new-session/model-control.test.ts
index 23ea29ec4977..f4d4f2a19f49 100644
--- a/ui/src/pages/new-session/model-control.test.ts
+++ b/ui/src/pages/new-session/model-control.test.ts
@@ -64,6 +64,41 @@ describe("new-session model runtime", () => {
     expect(control.cloudRuntimeUnsupportedReason(profile)).toBe(expected);
   });
 
+  it.each([
+    {
+      name: "allows opted-in remote execution",
+      runtimeId: "codex",
+      devicePlacement: {
+        requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+        consumesWorkerSlot: false,
+      },
+    },
+    {
+      name: "allows embedded execution",
+      runtimeId: "openclaw",
+      devicePlacement: { requiredNodeCommands: [], consumesWorkerSlot: true },
+    },
+    { name: "rejects a cloud-only runtime", runtimeId: "cloud-only" },
+    {
+      name: "rejects a stale support flag without an owner requirement",
+      runtimeId: "stale",
+      devicePlacementSupported: true,
+    },
+  ])("$name on paired devices", ({ runtimeId, devicePlacement, devicePlacementSupported }) => {
+    const control = new NewSessionModelControl(() => undefined);
+    vi.spyOn(control, "resolveAgentRuntime").mockReturnValue({
+      id: runtimeId,
+      cloudPlacementSupported: true,
+      devicePlacementSupported: devicePlacementSupported ?? Boolean(devicePlacement),
+      ...(devicePlacement ? { devicePlacement } : {}),
+      source: "model",
+    });
+
+    expect(control.devicePlacementUnsupportedReason()).toBe(
+      devicePlacement ? undefined : "This runtime does not support paired devices",
+    );
+  });
+
   it("keeps CLI agents hidden and undiscovered while the Labs gate is off", async () => {
     const { context, request } = contextWith([
       { id: "gpt-5.6-luna", name: "GPT-5.6 Luna", provider: "openai" },
diff --git a/ui/src/pages/new-session/model-control.ts b/ui/src/pages/new-session/model-control.ts
index 20a5135fc6ba..adad921c2a04 100644
--- a/ui/src/pages/new-session/model-control.ts
+++ b/ui/src/pages/new-session/model-control.ts
@@ -26,7 +26,6 @@ import type { NewSessionPreference } from "./preferences.ts";
 type NewSessionMetadataClient = NonNullable<ApplicationContext["gateway"]["snapshot"]["client"]>;
 type GatewayAgentRuntime = NonNullable<GatewayAgentRow["agentRuntime"]> & {
   cloudPlacementSupported?: boolean;
-  devicePlacementSupported?: boolean;
 };
 type NewSessionMetadataStatus = ChatModelCatalogState["status"];
 type NewSessionMetadataState = {
@@ -514,10 +513,11 @@ export class NewSessionModelControl {
   }
 
   devicePlacementUnsupportedReason(): string | undefined {
-    return this.resolveAgentRuntime({
+    const runtime = this.resolveAgentRuntime({
       agent: this.pendingAgent,
       context: this.pendingContext,
-    })?.devicePlacementSupported === false
+    });
+    return runtime && !runtime.devicePlacement
       ? t("newSession.deviceRuntimeUnsupported")
       : undefined;
   }
diff --git a/ui/src/pages/new-session/new-session-page.ts b/ui/src/pages/new-session/new-session-page.ts
index 9057dac1bcb4..4430dbc24093 100644
--- a/ui/src/pages/new-session/new-session-page.ts
+++ b/ui/src/pages/new-session/new-session-page.ts
@@ -375,6 +375,7 @@ export class NewSessionPage extends OpenClawLightDomElement {
       cloudProfileId: this.place.cloudProfileId,
       machineClass: this.place.machineClass,
       deviceId: this.place.deviceId,
+      devicePlacement: this.place.devicePlacementRequirement(),
       deviceDisabledReason: this.place.modelControl.devicePlacementUnsupportedReason(),
     });
     const projectState = resolveProjectChip({
diff --git a/ui/src/pages/new-session/where-chip.test.ts b/ui/src/pages/new-session/where-chip.test.ts
index 7b24be943771..5281ea0db45c 100644
--- a/ui/src/pages/new-session/where-chip.test.ts
+++ b/ui/src/pages/new-session/where-chip.test.ts
@@ -118,7 +118,7 @@ describe("Where chip", () => {
       cloudProfiles: [],
       cloudProfileId: "",
       deviceId: "",
-      deviceDisabledReason: "Needs the embedded runtime",
+      deviceDisabledReason: "This runtime does not support paired devices",
     });
     const container = document.createElement("div");
     render(
@@ -146,7 +146,90 @@ describe("Where chip", () => {
 
     const device = container.querySelector<HTMLButtonElement>('[data-value="device:macbook"]');
     expect(device?.disabled).toBe(true);
-    expect(device?.textContent).toContain("Needs the embedded runtime");
-    expect(device?.title).toBe("Needs the embedded runtime");
+    expect(device?.textContent).toContain("This runtime does not support paired devices");
+    expect(device?.title).toBe("This runtime does not support paired devices");
   });
+
+  it.each([
+    {
+      name: "allows enabled remote execution without a free worker slot",
+      devicePlacement: {
+        requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+        consumesWorkerSlot: false,
+      },
+      workerSlots: { total: 1, available: 0 },
+      invocableCommands: ["codex.exec-server.stdio.v1"],
+      disabled: false,
+    },
+    {
+      name: "keeps worker execution capacity-gated",
+      devicePlacement: { requiredNodeCommands: [], consumesWorkerSlot: true },
+      workerSlots: { total: 1, available: 0 },
+      invocableCommands: [],
+      disabled: true,
+      reason: /worker slots/i,
+    },
+    {
+      name: "disables a declared remote command that the Gateway has not enabled",
+      devicePlacement: {
+        requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+        consumesWorkerSlot: false,
+      },
+      workerSlots: { total: 1, available: 1 },
+      invocableCommands: [],
+      disabled: true,
+      reason: /enable|approv/i,
+    },
+  ])(
+    "$name in the New Session picker",
+    ({ devicePlacement, workerSlots, invocableCommands, disabled, reason }) => {
+      const state = resolveWhereChip({
+        environments: [
+          {
+            id: "node:runner",
+            type: "node",
+            label: "Build runner",
+            status: "available",
+            sessionHost: true,
+            workerSlots,
+            capabilities: ["codex.exec-server.stdio.v1"],
+            invocableCommands,
+          },
+        ],
+        cloudProfiles: [],
+        cloudProfileId: "",
+        deviceId: "",
+        devicePlacement,
+      });
+      const container = document.createElement("div");
+      render(
+        renderWhereChip({
+          state,
+          gatewayName: "",
+          cloudProfileId: "",
+          deviceId: "",
+          worktreeAvailable: true,
+          submitting: false,
+          pendingPlacement: false,
+          popoverOpen: true,
+          popoverHiding: false,
+          isAdmin: true,
+          onGuardTransition: vi.fn(),
+          onPopoverShow: vi.fn(),
+          onPopoverHide: vi.fn(),
+          onPopoverAfterHide: vi.fn(),
+          onSelectDevice: vi.fn(),
+          onSelectCloudProfile: vi.fn(),
+          onConnectMachine: vi.fn(),
+        }),
+        container,
+      );
+
+      const device = container.querySelector<HTMLButtonElement>('[data-value="device:runner"]');
+      expect(device?.disabled).toBe(disabled);
+      if (reason) {
+        expect(device?.title).toMatch(reason);
+      }
+    },
+  );
 });
diff --git a/ui/src/pages/new-session/where-chip.ts b/ui/src/pages/new-session/where-chip.ts
index f31640e04d98..ca4bea50eb73 100644
--- a/ui/src/pages/new-session/where-chip.ts
+++ b/ui/src/pages/new-session/where-chip.ts
@@ -7,7 +7,11 @@ import {
   renderConnectMachineMenuItem,
   renderSessionMenuItem,
 } from "./cloud-target.ts";
-import { projectDevicePlacements, type DevicePlacementOption } from "./device-placement.ts";
+import {
+  projectDevicePlacements,
+  type DevicePlacementOption,
+  type DevicePlacementRequirement,
+} from "./device-placement.ts";
 import type { DraftCloudProfile, DraftEnvironment, DraftMachineOption } from "./discovery.ts";
 
 type WhereChipState = Readonly<{
@@ -26,9 +30,10 @@ export function resolveWhereChip(params: {
   cloudProfileId: string;
   machineClass?: string;
   deviceId: string;
+  devicePlacement?: DevicePlacementRequirement;
   deviceDisabledReason?: string;
 }): WhereChipState {
-  const devices = projectDevicePlacements(params.environments);
+  const devices = projectDevicePlacements(params.environments, params.devicePlacement);
   const device = devices.find((candidate) => candidate.deviceId === params.deviceId);
   const profile = params.cloudProfiles.find((candidate) => candidate.id === params.cloudProfileId);
   if (params.cloudProfileId) {

From a4ae33990374642864b7d5a5f6930f935a514453 Mon Sep 17 00:00:00 2001
From: "Jason (Json)" <263060202+fuller-stack-dev@users.noreply.github.com>
Date: Fri, 21 Aug 2026 13:55:28 -0600
Subject: [PATCH 084/124] docs: prefer gh attach for PR media (#127417)

---
 .agents/skills/openclaw-pr-maintainer/SKILL.md | 4 +++-
 AGENTS.md                                      | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/.agents/skills/openclaw-pr-maintainer/SKILL.md b/.agents/skills/openclaw-pr-maintainer/SKILL.md
index 921f7b01f8b3..e1e091d290be 100644
--- a/.agents/skills/openclaw-pr-maintainer/SKILL.md
+++ b/.agents/skills/openclaw-pr-maintainer/SKILL.md
@@ -365,7 +365,9 @@ gh search issues --repo openclaw/openclaw --match title,body --limit 50 \
 - Stacked branches over a squash-merged parent: rebase with `git rebase --onto origin/main <landed-branch>`; a plain `git rebase origin/main` replays the parent's already-squashed commits and manufactures conflicts.
 - Non-main PRs: do not run `scripts/pr prepare-run` or `merge-run`; they diff against `main`. Use review artifacts, exact base-head CI, revalidate `headRefOid`, then `gh pr merge --match-head-commit <verified-sha>`.
 - PR-create merge-ref race recognition: the dropped/killed pull_request CI run appears as `startup_failure`/`BuildFailed` (`(Unknown event)`) and is not rerunnable — close/reopen or wait for the hourly `pr-ci-sweeper`; rerun attempts are wasted.
-- PR/issue media upload: 422 = unsupported type; 404 = bad repo id/no push. Video: `content_type` `video/mp4` or `video/webm`; embed the returned URL on its own bare line — GitHub renders a player, `![]()` does not; transcode Playwright webm via `ffmpeg -i in.webm -c:v libx264 -pix_fmt yuv420p out.mp4` for broad playback. Non-media artifacts or endpoint failure: Crabbox artifact publishing plus the manifest URL.
+- Preferred PR/issue media upload: when the command help exposes `--attach`, use the repeatable flag on `gh issue create`, `gh issue edit`, `gh issue comment`, and the matching `gh pr` commands. Example: `gh pr comment <pr> --repo openclaw/openclaw --body-file <comment.md> --attach <proof.mp4>`.
+- `gh --attach` video rules: accepted extensions are `.mp4`, `.mov`, and `.webm`; the local maximum is 100 MB, while GitHub's account limit may be lower. Do not add `#alt` to a video path. `gh` inserts a bare URL so GitHub renders a player, and the uploaded asset cannot be deleted.
+- Compatibility fallback: if the installed `gh` lacks `--attach`, use the raw user-attachments upload command in root `AGENTS.md`. For that endpoint, 422 = unsupported type and 404 = bad repo id/no push. Use `content_type` `video/mp4`, `video/quicktime`, or `video/webm`, and put the returned URL on its own bare line; `![]()` does not render the player. Transcode Playwright webm via `ffmpeg -i in.webm -c:v libx264 -pix_fmt yuv420p out.mp4` for broad playback. Non-media artifacts or endpoint failure: Crabbox artifact publishing plus the manifest URL.
 - Use standard Git commands and stage only the files intended for each commit.
 - Keep commit messages concise and action-oriented.
 - Group related changes; avoid bundling unrelated refactors.
diff --git a/AGENTS.md b/AGENTS.md
index 474bf5355f84..4c58997b3530 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -233,7 +233,9 @@ Review invariants; full doctrine: `docs/gateway/audit.md`.
 - PR create races GitHub's merge-ref computation and can silently drop or kill the pull_request CI run. Prevention: `gh pr create --draft`, poll `mergeable` non-null, then `gh pr ready`; verify CI attached to the head SHA — if missing, the hourly `pr-ci-sweeper` re-fires it, or close/reopen.
 - PR create/refresh: keep PR branches takeover-ready. Use a branch maintainers can push to, or for fork PRs ensure `maintainer_can_modify` / GitHub's `Allow edits by maintainers` is enabled unless explicitly told otherwise or GitHub's Actions/secrets warning makes that unsafe.
 - Contributor PRs: parsed context requires authored `What Problem This Solves` and `Evidence` sections. Do not require field-level proof forms; reviewers inspect code, tests, and CI for correctness.
-- PR/issue images/video: `curl -s "https://uploads.github.com/user-attachments/assets?name=<f>&content_type=<mime>&repository_id=<id>" -X POST -H "Authorization: Bearer $(gh auth token)" -H "Accept: application/json" --data-binary @<f>`; embed returned `.url` as markdown (video: bare line, not `![]()`). Same CDN as drag-drop; inherits repo visibility; no browser/computer use. Error semantics, video transcode, artifact fallback: `$openclaw-pr-maintainer`. Never push proof assets to any product repo branch; do not commit `.github/pr-assets`.
+- PR/issue images/video: when the installed `gh` command exposes `--attach`, use the repeatable flag on `gh issue create`, `gh issue edit`, `gh issue comment`, and the matching `gh pr` commands. Example: `gh pr comment <pr> --repo openclaw/openclaw --body-file <comment.md> --attach <proof.mp4>`; repeat `--attach <file>` for more files.
+- `gh --attach` accepts `.mp4`, `.mov`, and `.webm` videos up to 100 MB locally. GitHub's account limit may be lower. Do not add `#alt` to video paths; `gh` appends the uploaded URL as a bare line so GitHub renders a player. Uploaded assets cannot be deleted.
+- If the installed `gh` lacks `--attach`, use `curl -s "https://uploads.github.com/user-attachments/assets?name=<f>&content_type=<mime>&repository_id=<id>" -X POST -H "Authorization: Bearer $(gh auth token)" -H "Accept: application/json" --data-binary @<f>`; embed the returned `.url` as a bare line for video, not `![]()`. Both paths use the drag-drop CDN, inherit repository visibility, and require no browser/computer use. Error semantics, video transcode, artifact fallback: `$openclaw-pr-maintainer`. Never push proof assets to any product repo branch; do not commit `.github/pr-assets`.
 - CI polling: exact SHA, relevant checks only, minimal fields. Skip routine noise (`Auto response`, `Labeler`, docs agents, performance/stale). Logs only after failure/completion or concrete need. Never `gh run watch`; its 3s polling exhausts API quota. Use sparse GraphQL rollups. Filter `gh run list` by workflow/branch/commit; broad JSON lists can exceed relay caps. Exact-SHA fallback dispatches require the full 40-character SHA.
 - CI waits: `node scripts/watch-pr-ci.mjs <pr> <head-sha>` — prechecks mergeable (CONFLICTING = pull_request CI cannot attach) and run attachment before polling; watchers emit every terminal state; no unbounded polls.
 - Agent PR landing to `main`: only the repo-native `scripts/pr` wrapper — `review-init` -> `review-artifacts-init` -> `review-validate-artifacts` -> `OPENCLAW_TESTBOX=1 scripts/pr prepare-run` -> `merge-run`. The Testbox flag is mandatory for agents; invoke `prepare-run` only after exact-head CI is complete and green. Full mechanics (fork-code variant, drift policy, waits): `$openclaw-pr-maintainer`.

From 519877a3171d84c94ceeda538577711fba9e6eb2 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 13:09:31 -0700
Subject: [PATCH 085/124] fix(ui): surface session owner assignment failures
 (#127431)

Amp-Thread-ID: https://ampcode.com/threads/T-01a021f4-b547-7788-a916-d4a94cbd3e3b

Co-authored-by: Amp <amp@ampcode.com>
---
 .../session-organizer-operations.runtime.ts   |  13 +-
 ...session-organizer-owner-assignment.test.ts |  99 +++++++++++
 .../e2e/session-owner-assignment.e2e.test.ts  | 156 ++++++++++++++++++
 ui/src/pages/chat/chat-pane-session-menu.ts   |   4 +-
 4 files changed, 266 insertions(+), 6 deletions(-)
 create mode 100644 ui/src/components/session-organizer-owner-assignment.test.ts
 create mode 100644 ui/src/e2e/session-owner-assignment.e2e.test.ts

diff --git a/ui/src/components/session-organizer-operations.runtime.ts b/ui/src/components/session-organizer-operations.runtime.ts
index ea7fea560bbe..0564ef96cbf4 100644
--- a/ui/src/components/session-organizer-operations.runtime.ts
+++ b/ui/src/components/session-organizer-operations.runtime.ts
@@ -395,8 +395,8 @@ export async function renameSession(
 }
 
 export async function assignSessionOwner(
-  host: SessionOrganizerControllerHost,
-  session: SidebarRecentSession,
+  host: SessionActionHost,
+  session: Pick<SidebarRecentSession, "key">,
   owner: Pick<SessionOwnerOption, "type" | "id">,
   scope: SidebarSessionMutationScope,
 ): Promise<void> {
@@ -409,9 +409,16 @@ export async function assignSessionOwner(
   ) {
     return;
   }
-  await scope.sessions.assignOwner(session.key, owner, {
+  const assigned = await scope.sessions.assignOwner(session.key, owner, {
     agentId: parseAgentSessionKey(session.key)?.agentId ?? scope.selectedAgentId,
   });
+  if (
+    host.sessionData.isSessionMutationScopeCurrent(scope) &&
+    !assigned &&
+    scope.sessions.state.error
+  ) {
+    host.sessionData.publishSessionMutationError(scope, scope.sessions.state.error);
+  }
 }
 
 export async function createSessionGroup(
diff --git a/ui/src/components/session-organizer-owner-assignment.test.ts b/ui/src/components/session-organizer-owner-assignment.test.ts
new file mode 100644
index 000000000000..de8cfbf7f2fe
--- /dev/null
+++ b/ui/src/components/session-organizer-owner-assignment.test.ts
@@ -0,0 +1,99 @@
+/* @vitest-environment jsdom */
+
+import { describe, expect, it, vi } from "vitest";
+import type { ApplicationGatewaySnapshot } from "../app/gateway.ts";
+import type { SessionCapability } from "../lib/sessions/index.ts";
+import { gatewayHelloForMethods } from "../test-helpers/gateway-methods.ts";
+import type { SidebarSessionMutationScope } from "./app-sidebar-session-types.ts";
+import type { SessionActionHost } from "./session-organizer-batch-mutations.ts";
+import { assignSessionOwner } from "./session-organizer-operations.runtime.ts";
+
+function createHarness() {
+  let current = true;
+  let sessionError: string | null = null;
+  let settleAssignment: ((result: null) => void) | undefined;
+  const assignOwner = vi.fn(
+    () =>
+      new Promise<null>((resolve) => {
+        settleAssignment = resolve;
+      }),
+  );
+  const publishSessionMutationError = vi.fn();
+  const snapshot = {
+    client: {},
+    phase: "connected",
+    hello: gatewayHelloForMethods(["sessions.assignOwner"], ["operator.write"]),
+  } as ApplicationGatewaySnapshot;
+  const scope = {
+    gateway: { snapshot },
+    sessions: {
+      assignOwner,
+      get state() {
+        return { error: sessionError };
+      },
+    } as unknown as SessionCapability,
+    selectedAgentId: "main",
+  } as SidebarSessionMutationScope;
+  const host = {
+    sessionData: {
+      isSessionMutationScopeCurrent: vi.fn(() => current),
+      publishSessionMutationError,
+    },
+  } as unknown as SessionActionHost;
+  const session = {
+    key: "agent:main:owner-proof",
+  };
+  return {
+    assignOwner,
+    host,
+    publishSessionMutationError,
+    retire: () => {
+      current = false;
+    },
+    scope,
+    session,
+    setError: (error: string) => {
+      sessionError = error;
+    },
+    settle: () => settleAssignment?.(null),
+  };
+}
+
+describe("assignSessionOwner", () => {
+  it("publishes a current capability rejection at the action surface", async () => {
+    const harness = createHarness();
+    const pending = assignSessionOwner(
+      harness.host,
+      harness.session,
+      { type: "human", id: "profile-ada" },
+      harness.scope,
+    );
+
+    harness.setError("Owner assignment rejected.");
+    harness.settle();
+    await pending;
+
+    expect(harness.publishSessionMutationError).toHaveBeenCalledWith(
+      harness.scope,
+      "Owner assignment rejected.",
+    );
+  });
+
+  it("keeps a retired assignment rejection silent", async () => {
+    const harness = createHarness();
+    const pending = assignSessionOwner(
+      harness.host,
+      harness.session,
+      { type: "human", id: "profile-ada" },
+      harness.scope,
+    );
+
+    harness.setError("Retired assignment rejection.");
+    harness.retire();
+    harness.settle();
+    await pending;
+
+    expect(harness.assignOwner).toHaveBeenCalledOnce();
+    expect(harness.publishSessionMutationError).not.toHaveBeenCalled();
+  });
+});
diff --git a/ui/src/e2e/session-owner-assignment.e2e.test.ts b/ui/src/e2e/session-owner-assignment.e2e.test.ts
new file mode 100644
index 000000000000..cdbafdd3a33d
--- /dev/null
+++ b/ui/src/e2e/session-owner-assignment.e2e.test.ts
@@ -0,0 +1,156 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import type { Page } from "playwright";
+import { expect as expectBrowser } from "playwright/test";
+import { expect, it } from "vitest";
+import { controlUiSessionUrl, installMockGateway } from "../test-helpers/control-ui-e2e.ts";
+import { createControlUiE2eSuite } from "./control-ui-e2e-suite.test-support.ts";
+
+const suite = createControlUiE2eSuite({
+  name: "Control UI session owner assignment mocked Gateway E2E",
+  startServerBeforeBrowser: true,
+});
+const sessionKey = "agent:main:owner-outcome";
+const proofPhase = process.env.OPENCLAW_OWNER_ASSIGNMENT_PROOF_PHASE;
+const proofDir = path.resolve(".artifacts/control-ui-e2e/session-owner-assignment");
+
+function sessionsListResponse() {
+  return {
+    count: 2,
+    owners: [
+      { type: "human" as const, id: "profile-ada", label: "Ada" },
+      { type: "human" as const, id: "profile-bob", label: "Bob" },
+    ],
+    defaults: { contextTokens: null, model: null, modelProvider: null },
+    path: "",
+    sessions: [
+      {
+        key: "agent:main:ada-research",
+        kind: "direct",
+        label: "Ada research",
+        createdActor: { type: "human", id: "profile-ada", label: "Ada" },
+        owner: { actor: { type: "human", id: "profile-ada", label: "Ada" } },
+        updatedAt: 2,
+      },
+      {
+        key: sessionKey,
+        kind: "direct",
+        label: "Owner outcome",
+        createdActor: { type: "human", id: "profile-bob", label: "Bob" },
+        owner: { actor: { type: "human", id: "profile-bob", label: "Bob" } },
+        updatedAt: 1,
+      },
+    ],
+    ts: 1,
+  };
+}
+
+async function installOwnerGateway(page: Page) {
+  const gateway = await installMockGateway(page, {
+    featureMethods: ["chat.startup", "sessions.assignOwner"],
+    historyMessages: [{ role: "assistant", content: "Owner assignment outcome proof." }],
+    methodResponses: { "sessions.list": sessionsListResponse() },
+    operatorScopes: ["operator.read", "operator.write"],
+    presenceUsers: [{ self: true, id: "profile-ada", name: "Ada" }],
+    sessionKey,
+  });
+  await page.goto(controlUiSessionUrl(suite.server.baseUrl, sessionKey));
+  await page.getByText("Owner assignment outcome proof.", { exact: true }).waitFor();
+  await gateway.deferNext("sessions.assignOwner");
+  return gateway;
+}
+
+async function expectAssignmentRequest(
+  gateway: Awaited<ReturnType<typeof installOwnerGateway>>,
+): Promise<void> {
+  const request = await gateway.waitForRequest("sessions.assignOwner");
+  expect(request.params).toEqual({
+    agentId: "main",
+    key: sessionKey,
+    owner: { type: "human", id: "profile-ada" },
+  });
+}
+
+async function captureProof(page: Page, surface: string): Promise<void> {
+  if (!proofPhase) {
+    return;
+  }
+  await mkdir(proofDir, { recursive: true });
+  await page.screenshot({
+    animations: "disabled",
+    fullPage: true,
+    path: path.join(proofDir, `${surface}-${proofPhase}.png`),
+  });
+}
+
+async function chooseAssignToMe(page: Page): Promise<void> {
+  const action = page.locator('wa-dropdown-item[value="assign-owner:human:profile-ada"]:visible');
+  await action.waitFor({ state: "visible" });
+  await action.click();
+}
+
+suite.define(() => {
+  it("keeps a rejected header owner assignment visible", async () => {
+    await suite.withPage(
+      {
+        colorScheme: "dark",
+        locale: "en-US",
+        serviceWorkers: "block",
+        viewport: { height: 900, width: 1280 },
+      },
+      async ({ page }) => {
+        const gateway = await installOwnerGateway(page);
+        const activePane = page.locator("openclaw-chat-pane.chat-pane-cache__pane--active");
+        const menuTrigger = activePane.getByRole("button", { name: "Actions for Owner outcome" });
+        await menuTrigger.press("Enter");
+        await chooseAssignToMe(page);
+        await expectAssignmentRequest(gateway);
+
+        const message = "Owner assignment rejected for visible outcome proof.";
+        await gateway.rejectDeferred("sessions.assignOwner", {
+          code: "INVALID_REQUEST",
+          message,
+        });
+        await captureProof(page, "header");
+
+        await expectBrowser(
+          activePane.getByRole("alert").filter({ hasText: message }),
+        ).toBeVisible();
+        await expectBrowser(
+          activePane.getByRole("img", { name: "Created by Bob", exact: true }),
+        ).toHaveCount(1);
+      },
+    );
+  });
+
+  it("keeps a rejected sidebar owner assignment visible", async () => {
+    await suite.withPage(
+      {
+        locale: "en-US",
+        serviceWorkers: "block",
+        viewport: { height: 900, width: 1280 },
+      },
+      async ({ page }) => {
+        const gateway = await installOwnerGateway(page);
+        const row = page.locator(`[data-session-key="${sessionKey}"]`);
+        await row.hover();
+        await row
+          .getByRole("button", { name: "Open session menu: Owner outcome", exact: true })
+          .click();
+        await chooseAssignToMe(page);
+        await expectAssignmentRequest(gateway);
+
+        const message = "Sidebar owner assignment rejected for visible outcome proof.";
+        await gateway.rejectDeferred("sessions.assignOwner", {
+          code: "INVALID_REQUEST",
+          message,
+        });
+
+        await expectBrowser(page.getByRole("alert").filter({ hasText: message })).toBeVisible();
+        await expectBrowser(
+          row.getByRole("img", { name: "Created by Bob", exact: true }),
+        ).toHaveCount(1);
+      },
+    );
+  });
+});
diff --git a/ui/src/pages/chat/chat-pane-session-menu.ts b/ui/src/pages/chat/chat-pane-session-menu.ts
index 760126ae1f22..591e56198daa 100644
--- a/ui/src/pages/chat/chat-pane-session-menu.ts
+++ b/ui/src/pages/chat/chat-pane-session-menu.ts
@@ -113,9 +113,7 @@ export abstract class ChatPaneSessionMenu extends ChatPaneContext {
       };
       switch (action.kind) {
         case "assign-owner":
-          await scope.sessions.assignOwner(row.key, action.owner, {
-            agentId: parseAgentSessionKey(row.key)?.agentId ?? scope.selectedAgentId,
-          });
+          await operations.assignSessionOwner(host, session, action.owner, scope);
           break;
         case "fork":
           await operations.forkSession(host, session, scope);

From 229ce32e3272e92b08cfe7ed73b62ab68ecdbd6c Mon Sep 17 00:00:00 2001
From: ClawSweeper <steipete+clawsweeper@gmail.com>
Date: Fri, 21 Aug 2026 13:12:10 -0700
Subject: [PATCH 086/124] fix(ui): align run history dropdown text (#127443)

Co-authored-by: RoboClaw <309084314+roboclaw-bot@users.noreply.github.com>
Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>
---
 config/assertion-safety-baseline.txt          |  2 +-
 .../cron-run-filter-typography.e2e.test.ts    | 77 +++++++++++++++++++
 ui/src/e2e/cron-select-values.e2e.test.ts     | 15 ++--
 ui/src/pages/cron/view-runs.ts                | 55 ++++++++-----
 ui/src/pages/cron/view.test.ts                |  8 +-
 ui/src/styles/cron.css                        | 19 -----
 6 files changed, 129 insertions(+), 47 deletions(-)
 create mode 100644 ui/src/e2e/cron-run-filter-typography.e2e.test.ts

diff --git a/config/assertion-safety-baseline.txt b/config/assertion-safety-baseline.txt
index be6875c89154..c52b4bc7dfc2 100644
--- a/config/assertion-safety-baseline.txt
+++ b/config/assertion-safety-baseline.txt
@@ -4233,7 +4233,7 @@ ui/src/pages/config/view-schema.ts	2
 ui/src/pages/config/view.ts	5
 ui/src/pages/connection/connection-page.ts	1
 ui/src/pages/connection/view.ts	3
-ui/src/pages/cron/view-runs.ts	5
+ui/src/pages/cron/view-runs.ts	3
 ui/src/pages/cron/view.ts	9
 ui/src/pages/custodian/custodian-session-store.ts	1
 ui/src/pages/custodian/custodian-surface.ts	2
diff --git a/ui/src/e2e/cron-run-filter-typography.e2e.test.ts b/ui/src/e2e/cron-run-filter-typography.e2e.test.ts
new file mode 100644
index 000000000000..a92eb1a039a7
--- /dev/null
+++ b/ui/src/e2e/cron-run-filter-typography.e2e.test.ts
@@ -0,0 +1,77 @@
+import { expect, it } from "vitest";
+import { installMockGateway } from "../test-helpers/control-ui-e2e.ts";
+import { createControlUiE2eSuite } from "./control-ui-e2e-suite.test-support.ts";
+
+const suite = createControlUiE2eSuite({
+  name: "Control UI cron run filter typography E2E",
+  startServerBeforeBrowser: true,
+  unavailableMessage: (executablePath) =>
+    `Playwright Chromium is not installed or cannot start at ${executablePath}. Run \`pnpm --dir ui exec playwright install --with-deps chromium\`, or set OPENCLAW_UI_E2E_ALLOW_MISSING_CHROMIUM=1 only when intentionally skipping this lane.`,
+});
+
+suite.define(() => {
+  it("keeps dropdown text aligned at mobile and desktop widths", async () => {
+    for (const viewport of [
+      { height: 844, width: 390 },
+      { height: 900, width: 1_280 },
+    ]) {
+      await suite.withPage(
+        {
+          locale: "en-US",
+          serviceWorkers: "block",
+          viewport,
+        },
+        async ({ page }) => {
+          const gateway = await installMockGateway(page, {
+            methodResponses: {
+              "cron.list": {
+                jobs: [],
+                snapshotRevision: "cron-run-filter-typography",
+                total: 0,
+                offset: 0,
+                limit: 50,
+                hasMore: false,
+                nextOffset: null,
+              },
+              "cron.runs": {
+                entries: [],
+                total: 0,
+                offset: 0,
+                limit: 50,
+                hasMore: false,
+                nextOffset: null,
+              },
+              "cron.status": { enabled: true, jobs: 0, nextWakeAtMs: null },
+            },
+          });
+
+          await page.goto(`${suite.server.baseUrl}cron`);
+          await page.getByRole("tab", { name: "Run history", exact: true }).click();
+          const labels = page.locator(".cron-run-filters .cron-filter-dropdown__trigger span");
+          await expect.poll(() => labels.count()).toBe(3);
+          const fontSizes = await labels.evaluateAll((elements) =>
+            elements.map((element) => getComputedStyle(element).fontSize),
+          );
+          expect(new Set(fontSizes).size).toBe(1);
+
+          await page.getByRole("button", { name: "Sort Newest first", exact: true }).click();
+          await page.locator('wa-dropdown-item[value="asc"]').click();
+          await page.getByRole("button", { name: "Sort Oldest first", exact: true }).waitFor();
+          await expect
+            .poll(async () =>
+              (await gateway.getRequests("cron.runs")).some((request) => {
+                const params = request.params;
+                return (
+                  typeof params === "object" &&
+                  params !== null &&
+                  "sortDir" in params &&
+                  params.sortDir === "asc"
+                );
+              }),
+            )
+            .toBe(true);
+        },
+      );
+    }
+  });
+});
diff --git a/ui/src/e2e/cron-select-values.e2e.test.ts b/ui/src/e2e/cron-select-values.e2e.test.ts
index 1374d1f4c674..65cd178078af 100644
--- a/ui/src/e2e/cron-select-values.e2e.test.ts
+++ b/ui/src/e2e/cron-select-values.e2e.test.ts
@@ -45,14 +45,19 @@ suite.define(() => {
         const response = await page.goto(`${suite.server.baseUrl}cron`);
         expect(response?.status()).toBe(200);
         await page.locator('[data-test-id="cron-list-tab-activity"]').click();
-        const sort = page.locator("select.cron-run-sort");
+        const sortMenu = page.locator("wa-dropdown", { has: page.locator(".cron-run-sort") });
+        const sort = page.getByRole("button", { name: "Sort Newest first", exact: true });
         await sort.waitFor({ state: "visible" });
-        await sort.selectOption("asc");
-        expect(await sort.inputValue()).toBe("asc");
-        // Switching tabs recreates the select with the persisted non-first value.
+        await sort.click();
+        await sortMenu.locator('wa-dropdown-item[value="asc"]').click();
+        await page.getByRole("button", { name: "Sort Oldest first", exact: true }).waitFor();
+        // Switching tabs recreates the dropdown with the persisted non-first value.
         await page.locator('[data-test-id="cron-list-tab-tasks"]').click();
         await page.locator('[data-test-id="cron-list-tab-activity"]').click();
-        expect(await page.locator("select.cron-run-sort").inputValue()).toBe("asc");
+        await page.getByRole("button", { name: "Sort Oldest first", exact: true }).waitFor();
+        expect(
+          await sortMenu.locator('wa-dropdown-item[value="asc"]').getAttribute("aria-current"),
+        ).toBe("true");
         await page.locator('[data-test-id="cron-new-task"]').click();
 
         const pickerValue = (selector: string) =>
diff --git a/ui/src/pages/cron/view-runs.ts b/ui/src/pages/cron/view-runs.ts
index ed8c46d073ae..814d9f002254 100644
--- a/ui/src/pages/cron/view-runs.ts
+++ b/ui/src/pages/cron/view-runs.ts
@@ -223,8 +223,8 @@ export function renderRunsSection(props: CronRunsSectionProps) {
     .map((option) => option.label);
   const statusSummary = summarizeSelection(selectedStatusLabels, t("cron.runs.allStatuses"));
   const deliverySummary = summarizeSelection(selectedDeliveryLabels, t("cron.runs.allDelivery"));
-  // The sort select's .value binding commits before its options exist;
-  // selected attributes preserve non-first values.
+  const sortLabel =
+    props.runsSortDir === "asc" ? t("cron.runs.oldestFirst") : t("cron.runs.newestFirst");
   return html`
     <div class="cron-runs">
       ${props.conditionActivity ? renderConditionActivity(props.conditionActivity) : nothing}
@@ -273,23 +273,40 @@ export function renderRunsSection(props: CronRunsSectionProps) {
             void props.onRunsFiltersChange({ cronRunsDeliveryStatuses: [] });
           },
         })}
-        <select
-          class="cron-run-sort"
-          aria-label=${t("cron.jobs.sort")}
-          title=${t("cron.jobs.sort")}
-          .value=${props.runsSortDir}
-          @change=${(e: Event) =>
-            props.onRunsFiltersChange({
-              cronRunsSortDir: (e.target as HTMLSelectElement).value as CronSortDir,
-            })}
-        >
-          <option value="desc" ?selected=${props.runsSortDir === "desc"}>
-            ${t("cron.runs.newestFirst")}
-          </option>
-          <option value="asc" ?selected=${props.runsSortDir === "asc"}>
-            ${t("cron.runs.oldestFirst")}
-          </option>
-        </select>
+        <div class="cron-filter-dropdown">
+          <wa-dropdown
+            class="cron-filter-dropdown__details"
+            placement="bottom-start"
+            @wa-select=${(event: CustomEvent<{ item: { value?: string } }>) => {
+              const value = event.detail.item.value;
+              if (value === "asc" || value === "desc") {
+                void props.onRunsFiltersChange({ cronRunsSortDir: value });
+              }
+            }}
+          >
+            <button
+              slot="trigger"
+              type="button"
+              class="btn btn--sm cron-filter-dropdown__trigger cron-run-sort"
+              aria-label=${`${t("cron.jobs.sort")} ${sortLabel}`}
+            >
+              <span>${sortLabel}</span>
+              ${icon("chevronDown")}
+            </button>
+            <wa-dropdown-item value="desc" aria-current=${String(props.runsSortDir === "desc")}>
+              ${t("cron.runs.newestFirst")}
+              <span slot="details" aria-hidden="true">
+                ${props.runsSortDir === "desc" ? icon("check") : nothing}
+              </span>
+            </wa-dropdown-item>
+            <wa-dropdown-item value="asc" aria-current=${String(props.runsSortDir === "asc")}>
+              ${t("cron.runs.oldestFirst")}
+              <span slot="details" aria-hidden="true">
+                ${props.runsSortDir === "asc" ? icon("check") : nothing}
+              </span>
+            </wa-dropdown-item>
+          </wa-dropdown>
+        </div>
       </div>
       ${runs.length === 0
         ? hasRunFilters
diff --git a/ui/src/pages/cron/view.test.ts b/ui/src/pages/cron/view.test.ts
index 2323d70f4e04..00cdb56ad1ab 100644
--- a/ui/src/pages/cron/view.test.ts
+++ b/ui/src/pages/cron/view.test.ts
@@ -355,9 +355,11 @@ describe("cron view selects", () => {
 
   it("shows persisted non-first values in jobs filters and runs sort", () => {
     const activity = renderView({ listTab: "activity", runsSortDir: "asc" });
-    const sort = getElement(activity, "select.cron-run-sort", HTMLSelectElement);
-    expect(sort.value).toBe("asc");
-    expect(sort.querySelector('option[value="asc"]')?.hasAttribute("selected")).toBe(true);
+    const sort = getElement(activity, ".cron-run-sort", HTMLButtonElement);
+    expect(sort.textContent).toContain("Oldest first");
+    expect(
+      activity.querySelector('wa-dropdown-item[value="asc"]')?.getAttribute("aria-current"),
+    ).toBe("true");
     const tasks = renderView({ jobsLastStatusFilter: "error" });
     const lastStatus = getElement(
       tasks,
diff --git a/ui/src/styles/cron.css b/ui/src/styles/cron.css
index 083dc729944e..5eed30abdbd6 100644
--- a/ui/src/styles/cron.css
+++ b/ui/src/styles/cron.css
@@ -1033,25 +1033,6 @@
   }
 }
 
-/* Match the .btn--sm dropdown triggers beside it instead of the native look. */
-.cron-run-sort {
-  flex: 0 0 auto;
-  width: auto;
-  padding: 6px 10px;
-  font-size: 12px;
-  font-weight: 500;
-  color: var(--text);
-  border: 1px solid var(--border);
-  border-radius: var(--radius-md);
-  background: var(--bg-elevated);
-  cursor: var(--cursor-action);
-}
-
-.cron-run-sort:hover {
-  background: var(--bg-hover);
-  border-color: var(--border-strong);
-}
-
 .cron-runs__empty {
   font-size: 13px;
 }

From 731e9e768152855430b7270802f8808451afbfcc Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 13:18:11 -0700
Subject: [PATCH 087/124] perf(test): speed up browser extension state
 observations (#127471)

---
 .../chrome-extension/background.test-harness.ts    | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/extensions/browser/chrome-extension/background.test-harness.ts b/extensions/browser/chrome-extension/background.test-harness.ts
index bb4808577b3b..f309f632a37a 100644
--- a/extensions/browser/chrome-extension/background.test-harness.ts
+++ b/extensions/browser/chrome-extension/background.test-harness.ts
@@ -16,6 +16,10 @@ const PAIRING_CONFIG_KEYS = ["relayUrl", "token", "pairingStatus"];
 const RETIRED_CUSTODY_BLOCKED_KEY = "retiredCopilotCustodyBlockedV1";
 const backgroundCleanups = new Set<() => Promise<void>>();
 
+function waitForBackgroundState<T>(assertion: () => T | Promise<T>): Promise<T> {
+  return vi.waitFor(assertion, { interval: 1 });
+}
+
 export async function cleanupBackgroundHarnesses(): Promise<void> {
   await Promise.all([...backgroundCleanups].map(async (cleanup) => await cleanup()));
 }
@@ -388,7 +392,7 @@ export async function loadBackground({
   const backgroundModulePath = "./background.js";
   await import(backgroundModulePath);
   if (!deferRetiredStatePreparation) {
-    await vi.waitFor(() => {
+    await waitForBackgroundState(() => {
       const pairingReads = storageGet.mock.calls.filter(([keys]) =>
         PAIRING_CONFIG_KEYS.every((key) => keys.includes(key)),
       );
@@ -396,7 +400,7 @@ export async function loadBackground({
     });
   }
   if (!deferTabAccessInitialization && !deferRetiredStatePreparation) {
-    await vi.waitFor(() => {
+    await waitForBackgroundState(() => {
       const pairingWasCleared = storageRemove.mock.calls.some(([keys]) =>
         keys.includes("relayUrl"),
       );
@@ -482,7 +486,7 @@ export async function loadBackground({
       if (socket.readyState !== FakeWebSocket.OPEN) {
         socket.open();
       }
-      await vi.waitFor(() => expect(socket.send).toHaveBeenCalled());
+      await waitForBackgroundState(() => expect(socket.send).toHaveBeenCalled());
       const helloRaw = socket.send.mock.calls.find(
         ([raw]) => JSON.parse(raw).type === "auth.hello",
       )?.[0];
@@ -511,7 +515,7 @@ export async function loadBackground({
         ...fields,
         serverProof: await computeRelayAuthProof(String(storageValues.token), "server", fields),
       });
-      await vi.waitFor(() => {
+      await waitForBackgroundState(() => {
         expect(
           socket.send.mock.calls.some(([raw]) => JSON.parse(raw).type === "auth.response"),
         ).toBe(true);
@@ -534,7 +538,7 @@ export async function loadBackground({
           response.clientProof,
         ),
       });
-      await vi.waitFor(() => {
+      await waitForBackgroundState(() => {
         expect(socket.send.mock.calls.some(([raw]) => JSON.parse(raw).type === "hello")).toBe(true);
       });
     },

From 7909ea698374c945cbddb7bb6ffdd07ad88a9072 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 13:19:06 -0700
Subject: [PATCH 088/124] ci: remove the Test Performance Agent

The workflow ran a Codex agent over the full test suite and pushed
`test: optimize slow tests` straight to `main` under `contents: write`, with no
pull request and no human review. Its gates were a path allowlist, a
no-add/delete/rename rule, a non-decreasing total test count, and
`pnpm check:changed` -- which covers changed lanes, not the full suite. Test
optimization is exactly the class of change where a plausible edit can weaken
coverage without moving the test count, so unattended landing is the wrong
trade. Autonomous commits to `main` are not something this repo wants.

It had also been inert since well before this. The daily-cadence gate excluded
prior runs with `select(.status != "cancelled")`, but a finished cancelled run
reports `status: "completed"` with `conclusion: "cancelled"` -- verified against
run 32506655531, which that filter counts as a prior run. Its `concurrency`
block sets `cancel-in-progress: false`, so main's push rate produced dozens of
cancelled runs per hour and every trigger skipped, reporting green after ~2
minutes of doing nothing. No `test: optimize slow tests` commit has ever landed
on `main`.

`pnpm test:perf:groups` and the rest of the performance tooling it drove stay;
they are useful by hand and documented in docs/reference/test.md.

Repository secret OPENCLAW_TEST_PERF_AGENT_OPENAI_API_KEY now has no consumer
and can be deleted.
---
 .github/workflows/test-performance-agent.yml | 280 -------------------
 docs/ci.md                                   |   5 -
 docs/reference/test.md                       |   2 +-
 3 files changed, 1 insertion(+), 286 deletions(-)
 delete mode 100644 .github/workflows/test-performance-agent.yml

diff --git a/.github/workflows/test-performance-agent.yml b/.github/workflows/test-performance-agent.yml
deleted file mode 100644
index c80c9aeb76aa..000000000000
--- a/.github/workflows/test-performance-agent.yml
+++ /dev/null
@@ -1,280 +0,0 @@
-name: Test Performance Agent
-
-on:
-  workflow_run: # zizmor: ignore[dangerous-triggers] main-only test optimization after trusted CI; job gates repository, event, branch, actor, conclusion, current main SHA, and daily cadence before using write token
-    workflows:
-      - CI
-    types:
-      - completed
-  workflow_dispatch:
-
-permissions:
-  actions: read
-  contents: write
-
-concurrency:
-  group: test-performance-agent-main
-  cancel-in-progress: false
-
-env:
-  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
-  TEST_PERF_BEFORE: .artifacts/test-perf/baseline-before.json
-  TEST_PERF_AFTER: .artifacts/test-perf/after-agent.json
-  TEST_PERF_COMPARE: .artifacts/test-perf/agent-compare.json
-
-jobs:
-  optimize-tests:
-    if: >
-      github.repository == 'openclaw/openclaw' &&
-      (github.event_name == 'workflow_dispatch' ||
-        (github.event.workflow_run.conclusion == 'success' &&
-          github.event.workflow_run.event == 'push' &&
-          github.event.workflow_run.head_branch == 'main' &&
-          !endsWith(github.event.workflow_run.actor.login, '[bot]')))
-    runs-on: ubuntu-24.04
-    timeout-minutes: 240
-    steps:
-      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          ref: main
-          fetch-depth: 0
-          persist-credentials: false
-          submodules: false
-
-      - name: Gate trusted main activity and daily cadence
-        id: gate
-        env:
-          EVENT_NAME: ${{ github.event_name }}
-          GH_TOKEN: ${{ github.token }}
-          WORKFLOW_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
-        run: |
-          set -euo pipefail
-
-          if [ "$EVENT_NAME" != "workflow_run" ]; then
-            echo "run_agent=true" >> "$GITHUB_OUTPUT"
-            echo "base_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          for attempt in 1 2 3 4 5; do
-            if git fetch --no-tags origin main; then
-              break
-            fi
-            if [ "$attempt" = "5" ]; then
-              echo "Failed to fetch main after retries." >&2
-              exit 1
-            fi
-            echo "Fetch attempt ${attempt} failed; retrying."
-            sleep $((attempt * 2))
-          done
-
-          remote_main="$(git rev-parse origin/main)"
-          if [ "$remote_main" != "$WORKFLOW_HEAD_SHA" ]; then
-            echo "CI run is superseded by ${remote_main}; skipping test performance agent for ${WORKFLOW_HEAD_SHA}."
-            echo "run_agent=false" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          day_start="$(date -u +%Y-%m-%dT00:00:00Z)"
-          runs_json="$RUNNER_TEMP/test-performance-agent-runs.json"
-          gh api --method GET "repos/${GITHUB_REPOSITORY}/actions/workflows/test-performance-agent.yml/runs" \
-            -f branch=main \
-            -f event=workflow_run \
-            -f per_page=50 > "$runs_json"
-
-          prior_runs="$(
-            jq -r \
-              --argjson current_run_id "$GITHUB_RUN_ID" \
-              --arg day_start "$day_start" \
-              '.workflow_runs[]
-                | select(.database_id != $current_run_id)
-                | select(.created_at >= $day_start)
-                | select(.status != "cancelled")
-                | select((.conclusion // "") != "skipped")
-                | [.database_id, .status, (.conclusion // ""), .created_at, .head_sha]
-                | @tsv' "$runs_json"
-          )"
-
-          if [ -n "$prior_runs" ]; then
-            echo "Test performance agent already ran or is running today; skipping."
-            printf '%s\n' "$prior_runs"
-            echo "run_agent=false" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          echo "run_agent=true" >> "$GITHUB_OUTPUT"
-          echo "base_sha=${remote_main}" >> "$GITHUB_OUTPUT"
-
-      - name: Setup Node environment
-        if: steps.gate.outputs.run_agent == 'true'
-        uses: ./.github/actions/setup-node-env
-        with:
-          cache-mode: restore
-          install-bun: "false"
-
-      - name: Ensure test performance agent key exists
-        if: steps.gate.outputs.run_agent == 'true'
-        env:
-          OPENAI_API_KEY: ${{ secrets.OPENCLAW_TEST_PERF_AGENT_OPENAI_API_KEY || secrets.OPENAI_API_KEY }}
-        run: |
-          set -euo pipefail
-          if [ -z "${OPENAI_API_KEY:-}" ]; then
-            echo "Missing OPENCLAW_TEST_PERF_AGENT_OPENAI_API_KEY or OPENAI_API_KEY secret." >&2
-            exit 1
-          fi
-
-      - name: Build baseline full-suite performance report
-        if: steps.gate.outputs.run_agent == 'true'
-        run: pnpm test:perf:groups --full-suite --allow-failures --output "$TEST_PERF_BEFORE" --limit 20 --top-files 40
-
-      - name: Run Codex test performance agent
-        if: steps.gate.outputs.run_agent == 'true'
-        uses: openai/codex-action@52fe01ec70a42f454c9d2ebd47598f9fd6893d56
-        with:
-          openai-api-key: ${{ secrets.OPENCLAW_TEST_PERF_AGENT_OPENAI_API_KEY || secrets.OPENAI_API_KEY }}
-          prompt-file: .github/codex/prompts/test-performance-agent.md
-          model: ${{ vars.OPENCLAW_CI_OPENAI_MODEL_BARE }}
-          effort: high
-          sandbox: workspace-write
-          safety-strategy: drop-sudo
-          codex-args: '["--full-auto"]'
-
-      - name: Enforce focused test performance patch
-        if: steps.gate.outputs.run_agent == 'true'
-        id: patch
-        run: |
-          set -euo pipefail
-
-          untracked="$(git ls-files --others --exclude-standard)"
-          if [ -n "$untracked" ]; then
-            echo "Test performance agent created untracked files; forbidden:"
-            printf '%s\n' "$untracked"
-            exit 1
-          fi
-
-          added_deleted_or_renamed="$(git diff --name-status --diff-filter=ADR)"
-          if [ -n "$added_deleted_or_renamed" ]; then
-            echo "Test performance agent added, deleted, or renamed tracked files; forbidden:"
-            printf '%s\n' "$added_deleted_or_renamed"
-            exit 1
-          fi
-
-          bad_paths="$(
-            git diff --name-only | while IFS= read -r path; do
-              case "$path" in
-                apps/*|extensions/*|packages/*|scripts/*|src/*|test/*|ui/*) ;;
-                *) printf '%s\n' "$path" ;;
-              esac
-            done
-          )"
-          if [ -n "$bad_paths" ]; then
-            echo "Test performance agent touched forbidden paths:"
-            printf '%s\n' "$bad_paths"
-            exit 1
-          fi
-
-          if git diff --quiet; then
-            echo "has_changes=false" >> "$GITHUB_OUTPUT"
-          else
-            echo "has_changes=true" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Restore Node 24 path
-        if: steps.gate.outputs.run_agent == 'true' && steps.patch.outputs.has_changes == 'true'
-        run:
-          | # zizmor: ignore[github-env] NODE_BIN is set by the trusted local setup-node-env action in this same job
-          set -euo pipefail
-          export PATH="${NODE_BIN}:${PATH}"
-          echo "${NODE_BIN}" >> "$GITHUB_PATH"
-          node -v
-          corepack enable
-          pnpm -v
-
-      - name: Run full-suite performance report after agent changes
-        if: steps.gate.outputs.run_agent == 'true' && steps.patch.outputs.has_changes == 'true'
-        run: pnpm test:perf:groups --full-suite --output "$TEST_PERF_AFTER" --limit 20 --top-files 40
-
-      - name: Compare test performance reports
-        if: steps.gate.outputs.run_agent == 'true' && steps.patch.outputs.has_changes == 'true'
-        run: pnpm test:perf:groups:compare "$TEST_PERF_BEFORE" "$TEST_PERF_AFTER" --output "$TEST_PERF_COMPARE" --limit 20 --top-files 40
-
-      - name: Enforce coverage-preserving test count
-        if: steps.gate.outputs.run_agent == 'true' && steps.patch.outputs.has_changes == 'true'
-        run: |
-          set -euo pipefail
-          node <<'NODE'
-          const fs = require("node:fs");
-          const before = JSON.parse(fs.readFileSync(process.env.TEST_PERF_BEFORE, "utf8"));
-          const after = JSON.parse(fs.readFileSync(process.env.TEST_PERF_AFTER, "utf8"));
-
-          if (before.failed) {
-            console.log("Baseline had failing configs; skipping total test-count comparison against partial report.");
-            process.exit(0);
-          }
-
-          const beforeTests = before.totals?.testCount ?? 0;
-          const afterTests = after.totals?.testCount ?? 0;
-          if (afterTests < beforeTests) {
-            console.error(`Test count decreased from ${beforeTests} to ${afterTests}; refusing coverage-reducing patch.`);
-            process.exit(1);
-          }
-          console.log(`Test count preserved: ${beforeTests} -> ${afterTests}.`);
-          NODE
-
-      - name: Check changed lanes
-        if: steps.gate.outputs.run_agent == 'true' && steps.patch.outputs.has_changes == 'true'
-        run: pnpm check:changed
-
-      - name: Commit test performance updates
-        if: steps.gate.outputs.run_agent == 'true' && steps.patch.outputs.has_changes == 'true'
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
-          TARGET_BRANCH: main
-        run: |
-          set -euo pipefail
-
-          if git diff --quiet; then
-            echo "No test performance changes."
-            exit 0
-          fi
-
-          git config user.name "openclaw-test-performance-agent[bot]"
-          git config user.email "openclaw-test-performance-agent[bot]@users.noreply.github.com"
-          git add apps extensions packages scripts src test ui
-          git commit --no-verify -m "test: optimize slow tests"
-
-          for attempt in 1 2 3 4 5; do
-            if ! git fetch --no-tags origin "${TARGET_BRANCH}"; then
-              echo "Fetch attempt ${attempt} failed; retrying."
-              sleep $((attempt * 2))
-              continue
-            fi
-            if git push "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" HEAD:"${TARGET_BRANCH}"; then
-              exit 0
-            fi
-            remote_main="$(git rev-parse "origin/${TARGET_BRANCH}")"
-            if [ "$remote_main" != "$(git rev-parse HEAD^)" ]; then
-              echo "main advanced; rebasing test performance update onto ${remote_main}."
-              if ! git rebase "origin/${TARGET_BRANCH}"; then
-                echo "Test performance update no longer applies cleanly; skipping stale update."
-                git rebase --abort || true
-                exit 0
-              fi
-              pnpm check:changed
-            fi
-            echo "Test performance update attempt ${attempt} failed; retrying."
-            sleep $((attempt * 2))
-          done
-
-          echo "Failed to push test performance updates after retries." >&2
-          exit 1
-
-      - name: Upload test performance artifacts
-        if: steps.gate.outputs.run_agent == 'true' && always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
-        with:
-          name: test-performance-agent-${{ github.run_id }}
-          path: .artifacts/test-perf/
-          if-no-files-found: ignore
-          retention-days: 14
diff --git a/docs/ci.md b/docs/ci.md
index 3cc52aa816d2..17d39df2231f 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -55,7 +55,6 @@ dispatch.
 | `ios-build`                        | Swift lint, Debug and Release builds, focused simulator lifecycle tests, and the full release screenshot matrix when screenshot-pipeline owners changed                                                                                                                                                  | iOS/capture changes                                    |
 | `android`                          | Android unit tests for both flavors plus one debug APK build                                                                                                                                                                                                                                             | Android-relevant changes                               |
 | `openclaw/ci-gate`                 | Final aggregate: requires preflight and security; accepts skips only for manifest-disabled downstream lanes                                                                                                                                                                                              | Every non-draft CI run                                 |
-| `test-performance-agent`           | Separate workflow: daily Codex slow-test optimization after trusted activity                                                                                                                                                                                                                             | Main CI success or manual dispatch                     |
 | `openclaw-performance`             | Separate workflow: daily/on-demand Kova runtime performance reports with mock-provider, deep-profile, and GPT 5.6 live lanes                                                                                                                                                                             | Scheduled and manual dispatch                          |
 
 The rare path-triggered `docker-seed-e2e` job selects only the executable
@@ -726,10 +725,6 @@ Quality stays separate from security so quality findings can be scheduled, measu
 
 The `Docs Agent` workflow is an event-driven Codex maintenance lane for keeping existing docs aligned with recently landed changes. It has no pure schedule: a successful non-bot push CI run on `main` can trigger it, and manual dispatch can run it directly. Workflow-run invocations skip when `main` has moved on or when another non-skipped Docs Agent run was created in the last hour. When it runs, it reviews the commit range from the previous non-skipped Docs Agent source SHA to current `main`, so one hourly run can cover all main changes accumulated since the last docs pass.
 
-### Test Performance Agent
-
-The `Test Performance Agent` workflow is an event-driven Codex maintenance lane for slow tests. It has no pure schedule: a successful non-bot push CI run on `main` can trigger it, but it skips if another workflow-run invocation already ran or is running that UTC day. Manual dispatch bypasses that daily activity gate. The lane builds a full-suite grouped Vitest performance report, lets Codex make only small coverage-preserving test performance fixes instead of broad refactors, then reruns the full-suite report and rejects changes that reduce the passing baseline test count. The grouped report records per-config wall time and max RSS on Linux and macOS, so the before/after comparison surfaces test memory deltas beside duration deltas. If the baseline has failing tests, Codex may fix only obvious failures and the after-agent full-suite report must pass before anything is committed. When `main` advances before the bot push lands, the lane rebases the validated patch, reruns `pnpm check:changed`, and retries the push; conflicting stale patches are skipped. It uses GitHub-hosted Ubuntu so the Codex action can keep the same drop-sudo safety posture as the docs agent.
-
 ### Duplicate PRs After Merge
 
 The `Duplicate PRs After Merge` workflow is a manual maintainer workflow for post-land duplicate cleanup. It defaults to dry-run and only closes explicitly listed PRs when `apply=true`. Before mutating GitHub, it verifies that the landed PR is merged and that each duplicate has either a shared referenced issue or overlapping changed hunks.
diff --git a/docs/reference/test.md b/docs/reference/test.md
index b2103d742a10..5f24376016a7 100644
--- a/docs/reference/test.md
+++ b/docs/reference/test.md
@@ -198,7 +198,7 @@ If `pnpm test` flakes on a loaded host, rerun once before treating it as a regre
 - `pnpm test:perf:imports`: enables Vitest import-duration + import-breakdown reporting, while still using scoped lane routing for explicit file/directory targets. `pnpm test:perf:imports:changed` scopes the same profiling to files changed since `origin/main`.
 - `pnpm test:perf:changed:bench -- --ref <git-ref>` benchmarks the routed changed-mode path against the native root-project run for the same committed git diff; `pnpm test:perf:changed:bench -- --worktree` benchmarks the current worktree change set without committing first.
 - `pnpm test:perf:profile:main` writes a CPU profile for the Vitest main thread (`.artifacts/vitest-main-profile`); `pnpm test:perf:profile:runner` writes CPU + heap profiles for the unit runner (`.artifacts/vitest-runner-profile`).
-- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: runs every full-suite Vitest leaf config serially and writes grouped duration data plus per-config JSON/log artifacts. Full-suite reports isolate files by default so retained module graphs and GC pauses from earlier files are not charged to later assertions; pass `-- --no-isolate` only when intentionally profiling shared-worker accumulation. The Test Performance Agent uses this as its baseline before attempting slow-test fixes. `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json` compares grouped reports after a performance-focused change.
+- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: runs every full-suite Vitest leaf config serially and writes grouped duration data plus per-config JSON/log artifacts. Full-suite reports isolate files by default so retained module graphs and GC pauses from earlier files are not charged to later assertions; pass `-- --no-isolate` only when intentionally profiling shared-worker accumulation. `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json` compares grouped reports after a performance-focused change.
 - Full, extension, and include-pattern shard runs update local timing data in `.artifacts/vitest-shard-timings.json`; later whole-config runs use those timings to balance slow and fast shards. Include-pattern CI shards append the shard name to the timing key, which keeps filtered shard timings visible without replacing whole-config timing data. Set `OPENCLAW_TEST_PROJECTS_TIMINGS=0` to ignore the local timing artifact.
 
 ## Benchmarks

From 3ea90bdcdb30f2ad18a68203fee09fa7824170a1 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 13:21:43 -0700
Subject: [PATCH 089/124] feat(ui): add Person grouping mode for sessions
 sidebar and sessions page (#127346)

* feat(ui): add Person grouping mode for sessions sidebar and sessions page

Sessions can now be grouped by their durable owner identity: the sidebar
Group-by menu gains a capability-gated Person mode (self first, humans by
label, agent identities after; ownerless rows keep their smart zones), and
the sessions page gains the matching person mode. Person section headers
render the owner avatar and profile label; the mock dev server now
advertises the multi-identity policy and carries explicit row owners the
way the gateway projects createdActor fallbacks.

* feat(ui): gate sessions-page Person grouping on the identity capability

Mirrors the sidebar: the Person option hides without
hasMultipleSessionSharingIdentities and a stored Person preference
renders as None until the capability returns.
---
 scripts/control-ui-mock-dev.ts                |  9 ++-
 .../app-sidebar-session-list-render.ts        | 49 ++++++++---
 .../app-sidebar-session-menu-renderers.ts     | 17 ++--
 .../app-sidebar-session-navigation-logic.ts   | 10 +--
 .../app-sidebar-session-navigation.ts         | 35 ++++----
 ui/src/components/sidebar-menus-controller.ts |  2 +
 ui/src/components/sidebar-menus-render.ts     |  2 +-
 ui/src/i18n/locales/en.ts                     |  1 +
 ui/src/lib/sessions/grouping.test.ts          | 81 ++++++++++++++++++-
 ui/src/lib/sessions/grouping.ts               | 57 ++++++++++++-
 ui/src/pages/sessions/sessions-page.ts        |  7 +-
 ui/src/pages/sessions/view.test.ts            | 52 ++++++++++++
 ui/src/pages/sessions/view.ts                 | 15 +++-
 .../app-sidebar-cases/session-ownership.ts    | 75 +++++++++++++++++
 14 files changed, 360 insertions(+), 52 deletions(-)

diff --git a/scripts/control-ui-mock-dev.ts b/scripts/control-ui-mock-dev.ts
index 2b151fc65302..844d3a2f1c93 100644
--- a/scripts/control-ui-mock-dev.ts
+++ b/scripts/control-ui-mock-dev.ts
@@ -65,7 +65,7 @@ const MOCK_ACTOR_MIRA: SessionActorFixture = {
   id: "profile-mira",
   label: "Mira",
 };
-// These actors are also the effective owners because the mock rows are unassigned.
+// Rows carry explicit owners the way the gateway projects createdActor fallbacks.
 const MOCK_SESSION_OWNERS: readonly SessionActorFixture[] = [MOCK_ACTOR_PETER, MOCK_ACTOR_MIRA];
 
 const SESSION_PAGE_SIZE = 50;
@@ -1531,6 +1531,7 @@ async function createChatPickerScenario(
     sessionRow(NARRATION_DEMO_SESSION_KEY, "Sidebar narration demo", baseTime - 15_000, {
       createdActor: MOCK_ACTOR_MIRA,
       hasActiveRun: true,
+      owner: { actor: MOCK_ACTOR_MIRA },
       startedAt: baseTime - 45_000,
       status: "running",
     }),
@@ -1544,10 +1545,12 @@ async function createChatPickerScenario(
       category: "Research",
       createdActor: MOCK_ACTOR_MIRA,
       execCwd: "/Users/peter/Projects/clawdbot",
+      owner: { actor: MOCK_ACTOR_MIRA },
     }),
     sessionRow("agent:main:model-budget", "Model budget review", baseTime - 80_000, {
       category: "Research",
       execCwd: "/Users/peter/Projects/openclaw",
+      owner: { actor: { type: "human", id: "presence-riley", label: "Riley" } },
       status: "failed",
       lastRunError: "Model out of credits: openai/gpt-5.6",
     }),
@@ -1555,6 +1558,7 @@ async function createChatPickerScenario(
       createdActor: MOCK_ACTOR_PETER,
       execCwd: "/Users/peter/Work/openclaw",
       lastReadAt: baseTime - 120_000,
+      owner: { actor: MOCK_ACTOR_PETER },
       observerDigest: {
         headline: "Done: fixed the flaky retry-window test",
         health: "done",
@@ -1787,6 +1791,9 @@ async function createChatPickerScenario(
     // Terminal has a second gate beyond the advertised method (see
     // ui/src/lib/terminal-availability.ts).
     terminalEnabled: true,
+    // The mock rows span several owners; advertise the multi-identity policy
+    // so people-aware UI (People sort, Person grouping) is exercisable here.
+    hasMultipleSessionSharingIdentities: true,
     historyMessages,
     // Lights up the footer facepile and who's-online roster; the email-only
     // entry keeps the roster's no-display-name row exercised.
diff --git a/ui/src/components/app-sidebar-session-list-render.ts b/ui/src/components/app-sidebar-session-list-render.ts
index 9289fce9a4c0..94791308b716 100644
--- a/ui/src/components/app-sidebar-session-list-render.ts
+++ b/ui/src/components/app-sidebar-session-list-render.ts
@@ -59,17 +59,28 @@ function renderSessionSection(params: {
   const { host, section } = params;
   const totalRowCount = section.totalRowCount;
   const group = section.category;
+  const personOwner = section.personOwner;
   // Pinned rows render in the nav zone; renderHeader records whether this list
   // section owns collapse UI or sits directly below the global toolbar.
   const collapsed = section.renderHeader && host.collapsedSessionSections.has(section.id);
-  const label = section.groups
-    ? t("chat.sidebar.groups")
-    : section.work
-      ? t("chat.sidebar.coding")
-      : group
-        ? group
-        : t("chat.sidebar.otherSessions");
-  const zone = section.groups ? "groups" : section.work ? "coding" : group ? "category" : "threads";
+  const label = personOwner
+    ? personOwner.label || personOwner.id
+    : section.groups
+      ? t("chat.sidebar.groups")
+      : section.work
+        ? t("chat.sidebar.coding")
+        : group
+          ? group
+          : t("chat.sidebar.otherSessions");
+  const zone = personOwner
+    ? "person"
+    : section.groups
+      ? "groups"
+      : section.work
+        ? "coding"
+        : group
+          ? "category"
+          : "threads";
   // Collapsed Coding still signals live runs so background work stays visible.
   const collapsedRunningDot =
     collapsed &&
@@ -83,6 +94,7 @@ function renderSessionSection(params: {
     method: "sessions.groups.put",
     requiredScope: "operator.write",
   });
+  const sectionDropEnabled = groupWriteAccess.allowed && !personOwner;
   const sectionClass = [
     "sidebar-recent-sessions__group",
     `sidebar-recent-sessions__group--zone-${zone}`,
@@ -103,19 +115,21 @@ function renderSessionSection(params: {
     <div
       class=${sectionClass}
       data-session-section=${section.id}
-      @dragover=${groupWriteAccess.allowed
+      data-zone=${zone}
+      @dragover=${sectionDropEnabled
         ? (event: DragEvent) => host.sectionDragOver(event, section.id, group)
         : nothing}
-      @dragleave=${groupWriteAccess.allowed
+      @dragleave=${sectionDropEnabled
         ? (event: DragEvent) => host.sectionDragLeave(event, section.id, group)
         : nothing}
-      @drop=${groupWriteAccess.allowed
+      @drop=${sectionDropEnabled
         ? (event: DragEvent) => host.sectionDrop(event, section.id, group)
         : nothing}
     >
       ${section.renderHeader
         ? renderSidebarSessionSectionHeader({
             sectionId: section.id,
+            draggable: !personOwner,
             disabledReason: groupWriteAccess.allowed ? undefined : groupWriteAccess.reason,
             onStartDrag: (sectionId) => host.startSidebarSectionDrag(sectionId),
             onFinishDrag: () => host.finishSidebarSectionDrag(),
@@ -138,6 +152,19 @@ function renderSessionSection(params: {
                     >${collapsed ? icons.chevronRight : icons.chevronDown}</span
                   >
                 </span>
+                ${personOwner
+                  ? html`<openclaw-viewer-avatar
+                      .user=${{
+                        id: personOwner.id,
+                        name: personOwner.label,
+                        avatarUrl: personOwner.avatarUrl,
+                        watchedSessions: [],
+                      }}
+                      .markAsViewer=${false}
+                      variant="session"
+                      aria-hidden="true"
+                    ></openclaw-viewer-avatar>`
+                  : nothing}
                 <span class="sidebar-recent-sessions__label-text">${label}</span>
                 ${collapsed && totalRowCount > 0
                   ? html`<span class="sidebar-session-group-count">${totalRowCount}</span>`
diff --git a/ui/src/components/app-sidebar-session-menu-renderers.ts b/ui/src/components/app-sidebar-session-menu-renderers.ts
index 3015c9b9cea5..7d5cd4690423 100644
--- a/ui/src/components/app-sidebar-session-menu-renderers.ts
+++ b/ui/src/components/app-sidebar-session-menu-renderers.ts
@@ -294,6 +294,7 @@ export function renderSidebarSessionSortMenu(params: {
   }
   const groupingOptions = [
     { grouping: "category", label: t("sessionsView.groupByCategory") },
+    { grouping: "person", label: t("sessionsView.groupByPerson") },
     { grouping: "none", label: t("sessionsView.groupByNone") },
   ] as const satisfies ReadonlyArray<{ grouping: SidebarSessionsGrouping; label: string }>;
   return keyed(
@@ -336,13 +337,15 @@ export function renderSidebarSessionSortMenu(params: {
         >
           ${renderSidebarMenuTrigger(position, t("chat.sidebar.sortSessions"))}
           <div class="sidebar-session-sort-menu__title">${t("sessionsView.groupBy")}</div>
-          ${groupingOptions.map((option) =>
-            renderSidebarMenuRadioItem({
-              value: `grouping:${option.grouping}`,
-              checked: params.grouping === option.grouping,
-              label: option.label,
-            }),
-          )}
+          ${groupingOptions
+            .filter((option) => option.grouping !== "person" || params.peopleSortAvailable)
+            .map((option) =>
+              renderSidebarMenuRadioItem({
+                value: `grouping:${option.grouping}`,
+                checked: params.grouping === option.grouping,
+                label: option.label,
+              }),
+            )}
           <div class="session-menu__separator" role="separator"></div>
           <div class="sidebar-session-sort-menu__title">${t("chat.sidebar.sortBy")}</div>
           ${SIDEBAR_SESSION_SORT_OPTIONS.filter(
diff --git a/ui/src/components/app-sidebar-session-navigation-logic.ts b/ui/src/components/app-sidebar-session-navigation-logic.ts
index b22d8beda1ea..8afe28bb7222 100644
--- a/ui/src/components/app-sidebar-session-navigation-logic.ts
+++ b/ui/src/components/app-sidebar-session-navigation-logic.ts
@@ -308,18 +308,16 @@ export function partitionSidebarVisibleSections(input: {
   rows: SidebarRecentSession[];
   grouping: SidebarSessionsGrouping;
   knownGroups: string[] | undefined;
+  selfOwnerId?: string | null;
   catalogIds?: readonly string[];
   sectionOrder?: readonly string[];
   collapsedSections: ReadonlySet<string>;
   hideEmptyOwnerFilteredGroup: (category: string | undefined, rowCount: number) => boolean;
   visibleSessionLimits: ReadonlyMap<string, number>;
 }): SidebarVisibleSections {
-  const sections = groupSidebarSessionRows(input.rows, {
-    grouping: input.grouping,
-    knownGroups: input.knownGroups,
-    sectionOrder: input.sectionOrder,
-    catalogIds: input.catalogIds,
-  }).filter(
+  const { grouping, knownGroups, selfOwnerId, sectionOrder, catalogIds } = input;
+  const sectionOptions = { grouping, knownGroups, selfOwnerId, sectionOrder, catalogIds };
+  const sections = groupSidebarSessionRows(input.rows, sectionOptions).filter(
     (section) =>
       section.id !== "pinned" &&
       !input.hideEmptyOwnerFilteredGroup(section.category, section.rows.length),
diff --git a/ui/src/components/app-sidebar-session-navigation.ts b/ui/src/components/app-sidebar-session-navigation.ts
index 9dfc0733d639..e7e0f7b25c43 100644
--- a/ui/src/components/app-sidebar-session-navigation.ts
+++ b/ui/src/components/app-sidebar-session-navigation.ts
@@ -120,6 +120,13 @@ export class AppSidebarSessionNavigationElement extends AppSidebarBase {
     return resolveSidebarSessionSortMode(this.sessionSortMode, this.sessionPeopleSortAvailable());
   }
 
+  effectiveSessionsGrouping(): SidebarSessionsGrouping {
+    // Reconnects temporarily hide the capability; retain the stored Person
+    // preference so it returns when the authoritative identity policy does.
+    const grouping = this.sessionsGrouping;
+    return grouping === "person" && !this.sessionPeopleSortAvailable() ? "category" : grouping;
+  }
+
   setSessionSortMode(mode: SidebarSessionSortMode) {
     this.sessionSortMode = storeSidebarSessionSortMode(mode, this.sessionPeopleSortCapability());
   }
@@ -331,10 +338,12 @@ export class AppSidebarSessionNavigationElement extends AppSidebarBase {
 
   /** Collapsed zones keep full rows for true header counts and status dots. */
   protected zonedVisibleSections(rows: SidebarRecentSession[]): SidebarVisibleSections {
+    const grouping = this.effectiveSessionsGrouping();
     return partitionSidebarVisibleSections({
       rows,
-      grouping: this.sessionsGrouping,
-      knownGroups: this.sessionsGrouping === "category" ? this.knownSessionGroups() : [],
+      grouping,
+      knownGroups: grouping === "category" ? this.knownSessionGroups() : [],
+      selfOwnerId: this.context?.gateway.snapshot.selfUser?.id ?? null,
       // Normalize gateway order without dropping catalog-lagging categories.
       sectionOrder: this.knownSectionOrder(),
       catalogIds:
@@ -381,13 +390,10 @@ export class AppSidebarSessionNavigationElement extends AppSidebarBase {
     const rows = this.selectedAgentSessionRows(navigationState);
     const { visibleRows } = this.zonedVisibleSections(rows);
     const pinnedByKey = new Map(rows.filter((row) => row.pinned).map((row) => [row.key, row]));
-    const pinnedRows = this.reconciledSidebarZone().entries.flatMap((entry) =>
-      entry.type === "session"
-        ? pinnedByKey.get(entry.key)
-          ? [pinnedByKey.get(entry.key)!]
-          : []
-        : [],
-    );
+    const pinnedRows = this.reconciledSidebarZone().entries.flatMap((entry) => {
+      const row = entry.type === "session" ? pinnedByKey.get(entry.key) : undefined;
+      return row ? [row] : [];
+    });
     return [...pinnedRows, ...visibleRows];
   }
 
@@ -486,9 +492,7 @@ export class AppSidebarSessionNavigationElement extends AppSidebarBase {
 
   expandedAgentId(): string {
     const selected = normalizeOptionalString(this.context?.agentSelection.state.selectedId);
-    return selected
-      ? normalizeAgentId(selected)
-      : normalizeAgentId(this.getSessionNavigationState().selectedAgentId);
+    return normalizeAgentId(selected || this.getSessionNavigationState().selectedAgentId);
   }
 
   activeChipAgent() {
@@ -509,11 +513,8 @@ export class AppSidebarSessionNavigationElement extends AppSidebarBase {
   }
 
   private agentResumeKey(agentId: string): string {
-    return resolveSidebarAgentResumeKey(
-      this.latestAgentSessionRow(agentId),
-      agentId,
-      this.sessionMainKey(),
-    );
+    const latest = this.latestAgentSessionRow(agentId);
+    return resolveSidebarAgentResumeKey(latest, agentId, this.sessionMainKey());
   }
 
   /** Offline routes to Settings instead of a dead chat load. */
diff --git a/ui/src/components/sidebar-menus-controller.ts b/ui/src/components/sidebar-menus-controller.ts
index f90cf074180d..2bc0308974dc 100644
--- a/ui/src/components/sidebar-menus-controller.ts
+++ b/ui/src/components/sidebar-menus-controller.ts
@@ -17,6 +17,7 @@ import {
   sessionPullRequestsForGateway,
 } from "../lib/session-pull-requests.ts";
 import type { CatalogProjectGrouping } from "../lib/sessions/catalog-project-grouping.ts";
+import type { SidebarSessionsGrouping } from "../lib/sessions/grouping.ts";
 import { sessionNavigationTarget } from "../lib/sessions/route-navigation.ts";
 import { parseAgentSessionKey } from "../lib/sessions/session-key.ts";
 import { SidebarCatalogMenuController } from "./app-sidebar-catalog-menu.ts";
@@ -117,6 +118,7 @@ interface SidebarMenusControllerHost
   hideSessionCatalog(catalogId: string): void;
   sessionSortMode: SidebarSessionSortMode;
   effectiveSessionSortMode(): SidebarSessionSortMode;
+  effectiveSessionsGrouping(): SidebarSessionsGrouping;
   sessionPeopleSortAvailable(): boolean;
   setSessionSortMode(mode: SidebarSessionSortMode): void;
   readonly terminalAvailable: boolean;
diff --git a/ui/src/components/sidebar-menus-render.ts b/ui/src/components/sidebar-menus-render.ts
index 82d1f7d606ed..23bb0b62d150 100644
--- a/ui/src/components/sidebar-menus-render.ts
+++ b/ui/src/components/sidebar-menus-render.ts
@@ -380,7 +380,7 @@ export function renderSidebarSessionSortMenuForController(controller: SidebarMen
   return renderSidebarSessionSortMenu({
     position,
     trigger: controller.sessionSortMenuTrigger,
-    grouping: host.sessionsGrouping,
+    grouping: host.effectiveSessionsGrouping(),
     sortMode: host.effectiveSessionSortMode(),
     peopleSortAvailable: host.sessionPeopleSortAvailable(),
     statusFilter: host.sessionsStatusFilter,
diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts
index c33b6123ad13..019940ecdc28 100644
--- a/ui/src/i18n/locales/en.ts
+++ b/ui/src/i18n/locales/en.ts
@@ -1164,6 +1164,7 @@ export const en: TranslationMap = {
     groupBy: "Group by",
     groupByNone: "None",
     groupByCategory: "Custom groups",
+    groupByPerson: "Person",
     showSessionPreview: "Show message preview",
     showCronSessions: "Show automation sessions",
     showSystemSessions: "Show system sessions",
diff --git a/ui/src/lib/sessions/grouping.test.ts b/ui/src/lib/sessions/grouping.test.ts
index fdfdd583c48e..551b9b1a73fa 100644
--- a/ui/src/lib/sessions/grouping.test.ts
+++ b/ui/src/lib/sessions/grouping.test.ts
@@ -82,6 +82,68 @@ describe("groupSidebarSessionRows", () => {
     expect(sections[1]?.rows.map((item) => item.key)).toEqual(["tg"]);
   });
 
+  it("orders owner sections before stored zones and leaves ownerless rows in their smart zones", () => {
+    const sections = groupSidebarSessionRows(
+      [
+        row({ key: "agent", owner: { actor: { type: "agent", id: "agent-z", label: "Zed" } } }),
+        row({
+          key: "owned-group",
+          kind: "group",
+          category: "Ignored",
+          owner: { actor: { type: "human", id: "profile-b", label: "Bea" } },
+        }),
+        row({ key: "thread" }),
+        row({ key: "group", kind: "group" }),
+        row({ key: "work", workSession: true }),
+        row({ key: "human-a", owner: { actor: { type: "human", id: "profile-a", label: "Ada" } } }),
+        row({
+          key: "self",
+          owner: {
+            actor: {
+              type: "human",
+              id: "profile-self",
+              label: "Zoe",
+              avatarUrl: "/avatars/self",
+            },
+          },
+        }),
+        row({ key: "agent-a", owner: { actor: { type: "agent", id: "agent-a", label: "Alpha" } } }),
+        row({ key: "blank-owner", owner: { actor: { type: "human", id: "   " } } }),
+        row({ key: "pinned", pinned: true, owner: { actor: { type: "human", id: "profile-a" } } }),
+      ],
+      {
+        grouping: "person",
+        selfOwnerId: "profile-self",
+        knownGroups: ["Ignored"],
+        catalogIds: ["catalog"],
+        sectionOrder: ["work", "person:profile-b", "groups", "ungrouped", "catalog:catalog"],
+      },
+    );
+
+    expect(sections.map((section) => section.id)).toEqual([
+      "pinned",
+      "person:profile-self",
+      "person:profile-a",
+      "person:profile-b",
+      "person:agent-a",
+      "person:agent-z",
+      "work",
+      "groups",
+      "ungrouped",
+      "catalog:catalog",
+    ]);
+    expect(sections[1]?.personOwner).toEqual({
+      type: "human",
+      id: "profile-self",
+      label: "Zoe",
+      avatarUrl: "/avatars/self",
+    });
+    expect(sections[3]?.rows.map((item) => item.key)).toEqual(["owned-group"]);
+    expect(sections[6]?.rows.map((item) => item.key)).toEqual(["work"]);
+    expect(sections[7]?.rows.map((item) => item.key)).toEqual(["group"]);
+    expect(sections[8]?.rows.map((item) => item.key)).toEqual(["thread", "blank-owner"]);
+  });
+
   it("always emits threads and coding so the renderer can host fallbacks and catalogs", () => {
     expect(groupSidebarSessionRows([row({ key: "a" })]).map((section) => section.id)).toEqual([
       "ungrouped",
@@ -302,8 +364,9 @@ describe("moveSessionSection", () => {
 });
 
 describe("normalizeSidebarSessionsGrouping", () => {
-  it("accepts none and falls back to category grouping", () => {
+  it("accepts supported modes and falls back to category grouping", () => {
     expect(normalizeSidebarSessionsGrouping("none")).toBe("none");
+    expect(normalizeSidebarSessionsGrouping("person")).toBe("person");
     expect(normalizeSidebarSessionsGrouping("category")).toBe("category");
     expect(normalizeSidebarSessionsGrouping(null)).toBe("category");
     expect(normalizeSidebarSessionsGrouping("bogus")).toBe("category");
@@ -329,6 +392,7 @@ function row(
 describe("normalizeSessionsGroupBy", () => {
   it("accepts known modes and falls back to none", () => {
     expect(normalizeSessionsGroupBy("category")).toBe("category");
+    expect(normalizeSessionsGroupBy("person")).toBe("person");
     expect(normalizeSessionsGroupBy("date")).toBe("date");
     expect(normalizeSessionsGroupBy("bogus")).toBe("none");
     expect(normalizeSessionsGroupBy(null)).toBe("none");
@@ -362,6 +426,21 @@ describe("groupSessionRows", () => {
     expect(groups.map((group) => group.id)).toEqual(["discord", "telegram", UNGROUPED_ID]);
   });
 
+  it("groups sessions by their durable owner identity and leaves ownerless sessions last", () => {
+    const groups = groupSessionRows({
+      rows: [
+        row({ key: "bob", owner: { actor: { type: "human", id: "profile-b", label: "Bob" } } }),
+        row({ key: "ownerless" }),
+        row({ key: "ada", owner: { actor: { type: "human", id: " profile-a ", label: "Ada" } } }),
+        row({ key: "blank", owner: { actor: { type: "human", id: " " } } }),
+      ],
+      mode: "person",
+    });
+
+    expect(groups.map((group) => group.id)).toEqual(["profile-a", "profile-b", UNGROUPED_ID]);
+    expect(groups[2]?.rows.map((item) => item.key)).toEqual(["ownerless", "blank"]);
+  });
+
   it("preserves row order within a group", () => {
     const rows = [
       row({ key: "agent:main:discord:channel:1" }),
diff --git a/ui/src/lib/sessions/grouping.ts b/ui/src/lib/sessions/grouping.ts
index ec7c647b1334..501cdb4dc594 100644
--- a/ui/src/lib/sessions/grouping.ts
+++ b/ui/src/lib/sessions/grouping.ts
@@ -6,6 +6,7 @@ import { parseAgentSessionKey, parseSessionKeyParts } from "./session-key.ts";
 export const SESSION_GROUP_MODES = [
   "none",
   "category",
+  "person",
   "channel",
   "kind",
   "agent",
@@ -25,8 +26,16 @@ export type SessionRowGroup = {
 };
 
 export type SidebarSessionSection<Row> = {
-  id: "pinned" | "ungrouped" | "groups" | "work" | `category:${string}` | `catalog:${string}`;
+  id:
+    | "pinned"
+    | "ungrouped"
+    | "groups"
+    | "work"
+    | `category:${string}`
+    | `person:${string}`
+    | `catalog:${string}`;
   category?: string;
+  personOwner?: { type: string; id: string; label?: string; avatarUrl?: string };
   /** Built-in smart group-conversation section (kind "group" rows). */
   groups?: boolean;
   /** Built-in smart coding section (worktree/exec-node/ACP sessions). */
@@ -128,6 +137,8 @@ function resolveSessionGroupId(row: GatewaySessionRow, mode: SessionsGroupBy, no
   switch (mode) {
     case "category":
       return row.category?.trim() ?? UNGROUPED_ID;
+    case "person":
+      return row.owner?.actor.id?.trim() || UNGROUPED_ID;
     case "channel":
       return sessionRowChannel(row);
     case "kind":
@@ -169,16 +180,17 @@ export function groupSessionRows(params: {
   return ids.map((id) => ({ id, rows: byId.get(id) ?? [] }));
 }
 
-/** How the sidebar buckets non-pinned rows: category sections or one flat list. */
-export type SidebarSessionsGrouping = "category" | "none";
+/** How the sidebar buckets non-pinned rows before its built-in smart zones. */
+export type SidebarSessionsGrouping = "category" | "person" | "none";
 
 export function normalizeSidebarSessionsGrouping(raw: unknown): SidebarSessionsGrouping {
-  return raw === "none" ? "none" : "category";
+  return raw === "none" || raw === "person" ? raw : "category";
 }
 
 type SidebarGroupableRow = {
   pinned?: boolean;
   category?: string | null;
+  owner?: { actor: { type: string; id?: string; label?: string; avatarUrl?: string } };
   /** Session kind from the gateway row; "group" rows form the Groups zone. */
   kind?: string;
   /** Session bound to a managed worktree or exec node (Coding zone). */
@@ -216,6 +228,7 @@ export function groupSidebarSessionRows<Row extends SidebarGroupableRow>(
   options: {
     knownGroups?: readonly string[];
     grouping?: SidebarSessionsGrouping;
+    selfOwnerId?: string | null;
     sectionOrder?: readonly string[];
     catalogIds?: readonly string[];
   } = {},
@@ -226,6 +239,7 @@ export function groupSidebarSessionRows<Row extends SidebarGroupableRow>(
   const groups: Row[] = [];
   const coding: Row[] = [];
   const categories = new Map<string, Row[]>();
+  const people = new Map<string, SidebarSessionSection<Row>>();
   if (grouping === "category") {
     for (const name of options.knownGroups ?? []) {
       const trimmed = name.trim();
@@ -239,6 +253,26 @@ export function groupSidebarSessionRows<Row extends SidebarGroupableRow>(
       pinned.push(row);
       continue;
     }
+    const owner = grouping === "person" ? row.owner?.actor : undefined;
+    const ownerId = owner?.id?.trim();
+    if (owner && ownerId) {
+      const personSection = people.get(ownerId);
+      if (personSection) {
+        personSection.rows.push(row);
+      } else {
+        people.set(ownerId, {
+          id: `person:${ownerId}`,
+          personOwner: {
+            type: owner.type,
+            id: ownerId,
+            ...(owner.label ? { label: owner.label } : {}),
+            ...(owner.avatarUrl ? { avatarUrl: owner.avatarUrl } : {}),
+          },
+          rows: [row],
+        });
+      }
+      continue;
+    }
     const category = grouping === "category" ? row.category?.trim() : undefined;
     if (category) {
       const categoryRows = categories.get(category);
@@ -264,6 +298,21 @@ export function groupSidebarSessionRows<Row extends SidebarGroupableRow>(
   if (pinned.length > 0) {
     sections.push({ id: "pinned", rows: pinned });
   }
+  sections.push(
+    ...[...people.values()].toSorted((left, right) => {
+      const leftOwner = left.personOwner!;
+      const rightOwner = right.personOwner!;
+      const leftRank =
+        leftOwner.id === options.selfOwnerId ? 0 : leftOwner.type === "agent" ? 2 : 1;
+      const rightRank =
+        rightOwner.id === options.selfOwnerId ? 0 : rightOwner.type === "agent" ? 2 : 1;
+      return (
+        leftRank - rightRank ||
+        (leftOwner.label || leftOwner.id).localeCompare(rightOwner.label || rightOwner.id) ||
+        leftOwner.id.localeCompare(rightOwner.id)
+      );
+    }),
+  );
   const knownGroups = [
     ...new Set((options.knownGroups ?? []).map((name) => name.trim()).filter(Boolean)),
   ];
diff --git a/ui/src/pages/sessions/sessions-page.ts b/ui/src/pages/sessions/sessions-page.ts
index c75a5152922d..6d900556ad74 100644
--- a/ui/src/pages/sessions/sessions-page.ts
+++ b/ui/src/pages/sessions/sessions-page.ts
@@ -1510,6 +1510,8 @@ class SessionsPage extends OpenClawLightDomElement {
 
   override render() {
     const context = this.context;
+    const personGroupingAvailable =
+      context?.gateway.snapshot.hello?.policy?.hasMultipleSessionSharingIdentities === true;
     if (!context) {
       return html``;
     }
@@ -1559,7 +1561,10 @@ class SessionsPage extends OpenClawLightDomElement {
           ),
           sortColumn: this.sortColumn,
           sortDir: this.sortDir,
-          groupBy: this.groupBy,
+          // Same reconnect resilience as the sidebar: the stored Person
+          // preference survives a temporarily hidden identity capability.
+          groupBy: personGroupingAvailable || this.groupBy !== "person" ? this.groupBy : "none",
+          personGroupingAvailable,
           knownCategories: this.knownCategories(),
           page: this.page,
           pageSize: this.pageSize,
diff --git a/ui/src/pages/sessions/view.test.ts b/ui/src/pages/sessions/view.test.ts
index 26285eef43a8..f70ceae99223 100644
--- a/ui/src/pages/sessions/view.test.ts
+++ b/ui/src/pages/sessions/view.test.ts
@@ -49,6 +49,7 @@ function buildProps(result: SessionsListResult): SessionsProps {
     sortColumn: "updated",
     sortDir: "desc",
     groupBy: "none",
+    personGroupingAvailable: true,
     knownCategories: [],
     page: 0,
     pageSize: 10,
@@ -482,6 +483,57 @@ describe("sessions view", () => {
     expect(container.querySelectorAll(".session-data-row")).toHaveLength(1);
   });
 
+  it("offers person grouping and labels owner sections from their durable profile", async () => {
+    const container = document.createElement("div");
+    render(
+      renderSessions({
+        ...buildProps(
+          buildMultiResult([
+            {
+              key: "agent:main:ada",
+              kind: "direct",
+              updatedAt: 2,
+              owner: { actor: { type: "human", id: "profile-ada", label: "Ada Lovelace" } },
+            },
+            { key: "agent:main:ownerless", kind: "direct", updatedAt: 1 },
+          ]),
+        ),
+        groupBy: "person",
+      }),
+      container,
+    );
+    await Promise.resolve();
+
+    expect(
+      container
+        .querySelector<HTMLOptionElement>('.session-groupby__select option[value="person"]')
+        ?.textContent?.trim(),
+    ).toBe("Person");
+    expect(
+      [...container.querySelectorAll(".session-group-row__label")].map((label) =>
+        label.textContent?.trim(),
+      ),
+    ).toEqual(["Ada Lovelace", "Ungrouped"]);
+  });
+
+  it("hides the person grouping option without the identity capability", async () => {
+    const container = document.createElement("div");
+    render(
+      renderSessions({
+        ...buildProps(buildResult({ key: "agent:main:a", kind: "direct", updatedAt: 1 })),
+        personGroupingAvailable: false,
+      }),
+      container,
+    );
+    await Promise.resolve();
+
+    const modes = [
+      ...container.querySelectorAll<HTMLOptionElement>(".session-groupby__select option"),
+    ].map((option) => option.value);
+    expect(modes).not.toContain("person");
+    expect(modes).toContain("category");
+  });
+
   it("selects and names the current page size on first render", async () => {
     const container = document.createElement("div");
     render(
diff --git a/ui/src/pages/sessions/view.ts b/ui/src/pages/sessions/view.ts
index a4cd25169c9b..3fe4a8b60c76 100644
--- a/ui/src/pages/sessions/view.ts
+++ b/ui/src/pages/sessions/view.ts
@@ -90,6 +90,8 @@ export type SessionsProps = {
   sortColumn: "key" | "kind" | "updated" | "tokens";
   sortDir: "asc" | "desc";
   groupBy: SessionsGroupBy;
+  /** Multi-identity gateways only; hides the Person mode elsewhere. */
+  personGroupingAvailable: boolean;
   knownCategories: string[];
   page: number;
   pageSize: number;
@@ -780,6 +782,7 @@ function sessionsTableColumnCount(props: SessionsProps): number {
 const SESSION_GROUP_MODE_LABELS = {
   none: "sessionsView.groupByNone",
   category: "sessionsView.groupByCategory",
+  person: "sessionsView.groupByPerson",
   channel: "sessionsView.groupByChannel",
   kind: "sessionsView.groupByKind",
   agent: "sessionsView.groupByAgent",
@@ -790,7 +793,8 @@ function groupModeLabel(mode: SessionsGroupBy): string {
   return t(SESSION_GROUP_MODE_LABELS[mode] ?? SESSION_GROUP_MODE_LABELS.none);
 }
 
-function sessionGroupLabel(id: string, props: SessionsProps): string {
+function sessionGroupLabel(group: SessionRowGroup, props: SessionsProps): string {
+  const { id } = group;
   if (props.groupBy === "date") {
     const labels: Record<string, string> = {
       today: "sessionsView.dateToday",
@@ -811,6 +815,9 @@ function sessionGroupLabel(id: string, props: SessionsProps): string {
       return emoji ? `${emoji} ${name}` : name;
     }
   }
+  if (props.groupBy === "person") {
+    return group.rows[0]?.owner?.actor.label?.trim() || id;
+  }
   return id;
 }
 
@@ -856,7 +863,7 @@ function categoryDropHandlers(props: SessionsProps, category: string | null) {
 }
 
 function renderGroupHeaderRow(group: SessionRowGroup, props: SessionsProps) {
-  const label = sessionGroupLabel(group.id, props);
+  const label = sessionGroupLabel(group, props);
   const count =
     group.rows.length === 1
       ? t("sessionsView.groupRowCountOne", { count: "1" })
@@ -1215,7 +1222,9 @@ function renderSessionsTable(props: SessionsProps, ctx: SessionsTableContext) {
           @change=${(e: Event) =>
             props.onGroupByChange((e.target as HTMLSelectElement).value as SessionsGroupBy)}
         >
-          ${SESSION_GROUP_MODES.map(
+          ${SESSION_GROUP_MODES.filter(
+            (mode) => mode !== "person" || props.personGroupingAvailable,
+          ).map(
             (mode) =>
               html`<option value=${mode} ?selected=${props.groupBy === mode}>
                 ${groupModeLabel(mode)}
diff --git a/ui/src/test-helpers/app-sidebar-cases/session-ownership.ts b/ui/src/test-helpers/app-sidebar-cases/session-ownership.ts
index ee756d275016..2bcd2fb6c6c3 100644
--- a/ui/src/test-helpers/app-sidebar-cases/session-ownership.ts
+++ b/ui/src/test-helpers/app-sidebar-cases/session-ownership.ts
@@ -432,6 +432,81 @@ describe("AppSidebar session ownership", () => {
     expect(menu.querySelector('[value="sort:created"]')?.getAttribute("aria-checked")).toBe("true");
   });
 
+  it("groups sessions by owner only while the identity capability is available", async () => {
+    const gateway = createGatewayHarness({} as GatewayBrowserClient);
+    gateway.publish({ selfUser: { id: "profile-zoe", name: "Zoe" } });
+    const harness = createSessionsHarness("main", [
+      "agent:main:main",
+      "agent:main:ada",
+      "agent:main:zoe",
+    ]);
+    const result = harness.sessions.state.result;
+    const ada = result?.sessions.find((row) => row.key.endsWith(":ada"));
+    const zoe = result?.sessions.find((row) => row.key.endsWith(":zoe"));
+    if (!result || !ada || !zoe) {
+      throw new Error("expected owner rows");
+    }
+    setEffectiveOwner(ada, { type: "human", id: "profile-ada", label: "Ada" });
+    setEffectiveOwner(zoe, {
+      type: "human",
+      id: "profile-zoe",
+      label: "Zoe",
+      avatarUrl: "/avatars/zoe",
+    });
+    result.owners = [
+      { type: "human", id: "profile-ada", label: "Ada" },
+      { type: "human", id: "profile-zoe", label: "Zoe" },
+    ];
+
+    const { sidebar } = await mountSidebar(gateway.gateway, harness.sessions);
+    harness.publishList({ result, agentId: "main" });
+    await sidebar.updateComplete;
+
+    let menu = await openOwnerMenu(sidebar);
+    expect(menu.querySelector('[value="grouping:person"]')).toBeNull();
+    menu.dispatchEvent(new Event("wa-after-hide", { bubbles: true }));
+    await sidebar.updateComplete;
+
+    gateway.publish({ hello: sessionSharingHello(true) });
+    await sidebar.updateComplete;
+    await selectSessionMenuValue(sidebar, "grouping:person");
+
+    const ownerSections = () => [
+      ...sidebar.querySelectorAll<HTMLElement>('[data-session-section^="person:"]'),
+    ];
+    expect(ownerSections().map((section) => section.dataset.sessionSection)).toEqual([
+      "person:profile-zoe",
+      "person:profile-ada",
+    ]);
+    expect(
+      ownerSections()[0]?.querySelector(".sidebar-recent-sessions__label-text")?.textContent,
+    ).toBe("Zoe");
+    expect(
+      ownerSections()[0]?.querySelector("openclaw-viewer-avatar")?.getAttribute("aria-hidden"),
+    ).toBe("true");
+    expect(
+      ownerSections()[0]
+        ?.querySelector(".sidebar-recent-sessions__head")
+        ?.getAttribute("draggable"),
+    ).toBe("false");
+    expect(ownerSections()[0]?.querySelector(".sidebar-session-group-actions")).toBeNull();
+
+    gateway.publish({ hello: null });
+    await sidebar.updateComplete;
+    expect(ownerSections()).toHaveLength(0);
+    menu = await openOwnerMenu(sidebar);
+    expect(menu.querySelector('[value="grouping:person"]')).toBeNull();
+    expect(menu.querySelector('[value="grouping:category"]')?.getAttribute("aria-checked")).toBe(
+      "true",
+    );
+    menu.dispatchEvent(new Event("wa-after-hide", { bubbles: true }));
+    await sidebar.updateComplete;
+
+    gateway.publish({ hello: sessionSharingHello(true) });
+    await sidebar.updateComplete;
+    expect(ownerSections()).toHaveLength(2);
+  });
+
   it("shows archive attribution only in collaborative archived-session lists", async () => {
     const gateway = createGateway({} as GatewayBrowserClient);
     const harness = createSessionsHarness("main", [

From 959adf6f33e1eb4bbe1865c2465da1e65d4c0950 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 13:30:53 -0700
Subject: [PATCH 090/124] perf(cron): summarize timer schedule in one pass
 (#127495)

Co-authored-by: Amp <amp@ampcode.com>
---
 src/cron/service.armtimer-tight-loop.test.ts | 134 ++++++++++++-------
 src/cron/service/jobs-scheduling.ts          |  30 ++++-
 src/cron/service/timer-scheduler.ts          |  12 +-
 3 files changed, 118 insertions(+), 58 deletions(-)

diff --git a/src/cron/service.armtimer-tight-loop.test.ts b/src/cron/service.armtimer-tight-loop.test.ts
index 24ba29474f3d..54e06985d44c 100644
--- a/src/cron/service.armtimer-tight-loop.test.ts
+++ b/src/cron/service.armtimer-tight-loop.test.ts
@@ -112,7 +112,7 @@ describe("CronService - armTimer tight loop prevention", () => {
     timeoutSpy.mockRestore();
   });
 
-  it("does not add extra delay when the next wake time is in the future", () => {
+  it("reads enabled and collection length only during one future-wake traversal", () => {
     const timeoutSpy = vi.spyOn(globalThis, "setTimeout");
     const now = Date.parse("2026-02-28T12:32:00.000Z");
 
@@ -120,34 +120,58 @@ describe("CronService - armTimer tight loop prevention", () => {
       storePath: "/tmp/test-cron/jobs.json",
       now,
     });
+    const job: CronJob = {
+      id: "future-job",
+      name: "future-job",
+      enabled: true,
+      deleteAfterRun: false,
+      createdAtMs: now,
+      updatedAtMs: now,
+      schedule: { kind: "cron", expr: "*/15 * * * *" },
+      sessionTarget: "isolated",
+      wakeMode: "next-heartbeat",
+      payload: { kind: "agentTurn", message: "test" },
+      delivery: { mode: "none" },
+      state: { nextRunAtMs: now + 10_000 },
+    };
+    let enabledReads = 0;
+    Object.defineProperty(job, "enabled", {
+      configurable: true,
+      get: () => {
+        enabledReads += 1;
+        if (enabledReads > 1) {
+          throw new Error("enabled read more than once");
+        }
+        return true;
+      },
+    });
+    let lengthReads = 0;
+    const jobs = new Proxy([job], {
+      get(target, property, receiver) {
+        if (property === "length") {
+          lengthReads += 1;
+          if (lengthReads > target.length + 1) {
+            throw new Error("jobs.length read after iteration");
+          }
+        }
+        return Reflect.get(target, property, receiver);
+      },
+    });
     state.store = {
       version: 1,
-      jobs: [
-        {
-          id: "future-job",
-          name: "future-job",
-          enabled: true,
-          deleteAfterRun: false,
-          createdAtMs: now,
-          updatedAtMs: now,
-          schedule: { kind: "cron", expr: "*/15 * * * *" },
-          sessionTarget: "isolated" as const,
-          wakeMode: "next-heartbeat" as const,
-          payload: { kind: "agentTurn" as const, message: "test" },
-          delivery: { mode: "none" as const },
-          state: { nextRunAtMs: now + 10_000 }, // 10 seconds in the future
-        },
-      ],
+      jobs,
     };
 
-    armTimer(state);
+    try {
+      armTimer(state);
 
-    const delays = extractTimeoutDelays(timeoutSpy);
-
-    // The natural delay (10 s) should be used, not the floor.
-    expect(delays).toContain(10_000);
-
-    timeoutSpy.mockRestore();
+      expect(enabledReads).toBe(1);
+      expect(lengthReads).toBe(2);
+      expect(state.timer).toBe(latestTimeoutHandle(timeoutSpy));
+      expect(extractTimeoutDelays(timeoutSpy)).toContain(10_000);
+    } finally {
+      timeoutSpy.mockRestore();
+    }
   });
 
   it("keeps a maintenance wake armed when enabled jobs have no nextRunAtMs", () => {
@@ -158,33 +182,51 @@ describe("CronService - armTimer tight loop prevention", () => {
       storePath: "/tmp/test-cron/jobs.json",
       now,
     });
+    const job: CronJob = {
+      id: "missing-next-run",
+      name: "missing-next-run",
+      enabled: true,
+      deleteAfterRun: false,
+      createdAtMs: now - 60_000,
+      updatedAtMs: now - 30_000,
+      schedule: { kind: "cron", expr: "*/15 * * * *" },
+      sessionTarget: "isolated",
+      wakeMode: "next-heartbeat",
+      payload: { kind: "agentTurn", message: "test" },
+      delivery: { mode: "none" },
+      state: {
+        lastRunStatus: "error",
+        lastRunAtMs: now - 45_000,
+        lastError: "provider overloaded",
+      },
+    };
+    const jobs = [job];
+    const filterSpy = vi.spyOn(jobs, "filter");
     state.store = {
       version: 1,
-      jobs: [
-        {
-          id: "missing-next-run",
-          name: "missing-next-run",
-          enabled: true,
-          deleteAfterRun: false,
-          createdAtMs: now - 60_000,
-          updatedAtMs: now - 60_000,
-          schedule: { kind: "cron", expr: "*/15 * * * *" },
-          sessionTarget: "isolated" as const,
-          wakeMode: "next-heartbeat" as const,
-          payload: { kind: "agentTurn" as const, message: "test" },
-          delivery: { mode: "none" as const },
-          state: {},
-        },
-      ],
+      jobs,
     };
 
-    armTimer(state);
+    try {
+      armTimer(state);
 
-    expect(state.timer).toBe(latestTimeoutHandle(timeoutSpy));
-    const delays = extractTimeoutDelays(timeoutSpy);
-    expect(delays).toContain(60_000);
-
-    timeoutSpy.mockRestore();
+      expect(state.timer).toBe(latestTimeoutHandle(timeoutSpy));
+      expect(extractTimeoutDelays(timeoutSpy)).toContain(60_000);
+      expect(filterSpy).not.toHaveBeenCalled();
+      expect(state.store.jobs).toEqual([job]);
+      expect(state.store.jobs[0]).toBe(job);
+      expect(job.state).toEqual({
+        lastRunStatus: "error",
+        lastRunAtMs: now - 45_000,
+        lastError: "provider overloaded",
+      });
+      expect(noopLogger.debug).toHaveBeenLastCalledWith(
+        { jobCount: 1, enabledCount: 1, withNextRun: 0, delayMs: 60_000 },
+        "cron: timer armed for maintenance recheck",
+      );
+    } finally {
+      timeoutSpy.mockRestore();
+    }
   });
 
   it("breaks the onTimer→armTimer hot-loop with stuck runningAtMs", async () => {
diff --git a/src/cron/service/jobs-scheduling.ts b/src/cron/service/jobs-scheduling.ts
index 211f7271822a..e063b485a793 100644
--- a/src/cron/service/jobs-scheduling.ts
+++ b/src/cron/service/jobs-scheduling.ts
@@ -731,16 +731,36 @@ export function recomputeNextRunsForMaintenance(
   return changed;
 }
 
-/** Returns the next enabled wake timestamp from the in-memory cron store. */
-export function nextWakeAtMs(state: CronServiceState) {
+/** Summarizes the resident job schedule in one pass for timer and status projections. */
+export function summarizeCronJobSchedule(state: CronServiceState) {
+  const jobs = state.store?.jobs ?? [];
   let nextWake: number | undefined;
-  for (const job of state.store?.jobs ?? []) {
+  let jobCount = 0;
+  let enabledCount = 0;
+  for (const job of jobs) {
+    jobCount += 1;
     const nextRun = job.state.nextRunAtMs;
-    if (isJobEnabled(job) && hasScheduledNextRunAtMs(nextRun)) {
+    const hasNextRun = hasScheduledNextRunAtMs(nextRun);
+    const rawEnabled = job.enabled;
+    // Timer diagnostics historically count only explicit enablement, while
+    // wake selection keeps older jobs without `enabled` runnable.
+    if (rawEnabled) {
+      enabledCount += 1;
+    }
+    if ((rawEnabled ?? true) && hasNextRun) {
       nextWake = nextWake === undefined ? nextRun : Math.min(nextWake, nextRun);
     }
   }
-  return nextWake;
+  return {
+    jobCount,
+    enabledCount,
+    nextWakeAtMs: nextWake,
+  };
+}
+
+/** Returns the next enabled wake timestamp from the in-memory cron store. */
+export function nextWakeAtMs(state: CronServiceState) {
+  return summarizeCronJobSchedule(state).nextWakeAtMs;
 }
 
 /** Applies one canonical server-authored authority envelope to a tool-bearing job. */
diff --git a/src/cron/service/timer-scheduler.ts b/src/cron/service/timer-scheduler.ts
index 34dc7efb73d9..03b5a88a4bd0 100644
--- a/src/cron/service/timer-scheduler.ts
+++ b/src/cron/service/timer-scheduler.ts
@@ -13,7 +13,7 @@ import {
 } from "../store/run-receipt-store.js";
 import type { CronJob } from "../types.js";
 import { enrollForeignReceipt } from "./foreign-receipt-monitor.js";
-import { hasScheduledNextRunAtMs, nextWakeAtMs } from "./jobs-scheduling.js";
+import { summarizeCronJobSchedule } from "./jobs-scheduling.js";
 import { locked } from "./locked.js";
 import {
   cleanupQueuedCronRunReservations,
@@ -60,13 +60,11 @@ export function armTimer(state: CronServiceState) {
     state.deps.log.debug({}, "cron: armTimer skipped - scheduler disabled");
     return;
   }
-  const nextAt = nextWakeAtMs(state);
+  const { nextWakeAtMs: nextAt, jobCount, enabledCount } = summarizeCronJobSchedule(state);
   if (!nextAt) {
-    const jobCount = state.store?.jobs.length ?? 0;
-    const enabledCount = state.store?.jobs.filter((j) => j.enabled).length ?? 0;
-    const withNextRun =
-      state.store?.jobs.filter((j) => j.enabled && hasScheduledNextRunAtMs(j.state.nextRunAtMs))
-        .length ?? 0;
+    // The summary uses the same scheduled-timestamp predicate as this branch,
+    // so no explicitly enabled job can have a next run here.
+    const withNextRun = 0;
     if (enabledCount > 0) {
       armRunningRecheckTimer(state);
       state.deps.log.debug(

From 3bb1433b78559a85b96ebbfd21260dfb52bb88e2 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 13:37:31 -0700
Subject: [PATCH 091/124] fix(ui): surface config open-file failures (#127498)

Amp-Thread-ID: https://ampcode.com/threads/T-01a021f4-b547-7788-a916-d4a94cbd3e3b

Co-authored-by: Amp <amp@ampcode.com>
---
 .../e2e/config-open-file-feedback.e2e.test.ts | 115 ++++++++++++++++++
 .../lib/config/config-gateway-operations.ts   |  44 ++++---
 2 files changed, 136 insertions(+), 23 deletions(-)
 create mode 100644 ui/src/e2e/config-open-file-feedback.e2e.test.ts

diff --git a/ui/src/e2e/config-open-file-feedback.e2e.test.ts b/ui/src/e2e/config-open-file-feedback.e2e.test.ts
new file mode 100644
index 000000000000..14765d548dce
--- /dev/null
+++ b/ui/src/e2e/config-open-file-feedback.e2e.test.ts
@@ -0,0 +1,115 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import type { Page } from "playwright";
+import { expect, it } from "vitest";
+import { installMockGateway } from "../test-helpers/control-ui-e2e.ts";
+import { createControlUiE2eSuite } from "./control-ui-e2e-suite.test-support.ts";
+
+const suite = createControlUiE2eSuite({
+  name: "Control UI config open-file feedback mocked Gateway E2E",
+  startServerBeforeBrowser: true,
+});
+const configPath = "/tmp/openclaw-config-open-feedback/openclaw.json";
+const captureProof = process.env.OPENCLAW_CAPTURE_UI_PROOF === "1";
+const proofPath = path.resolve(".artifacts/control-ui-e2e/config-open-file-feedback/after.png");
+
+async function installClipboardProof(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    const copied: string[] = [];
+    Object.defineProperty(globalThis, "configOpenFileCopied", { value: copied });
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      value: {
+        writeText: async (text: string) => {
+          copied.push(text);
+        },
+      },
+    });
+  });
+}
+
+async function openRawSettings(page: Page, response?: unknown) {
+  await installClipboardProof(page);
+  const config = { laboratory: { enabled: true } };
+  const gateway = await installMockGateway(page, {
+    featureMethods: ["config.openFile"],
+    methodResponses: {
+      "config.get": {
+        config,
+        hash: "config-open-file-feedback",
+        issues: [],
+        path: configPath,
+        raw: JSON.stringify(config),
+        valid: true,
+      },
+      "config.schema": {
+        schema: {
+          type: "object",
+          properties: {
+            laboratory: {
+              type: "object",
+              properties: { enabled: { type: "boolean" } },
+            },
+          },
+        },
+        uiHints: {},
+        version: "config-open-file-feedback",
+      },
+      ...(response === undefined ? {} : { "config.openFile": response }),
+    },
+    operatorScopes: ["operator.read", "operator.admin"],
+  });
+  const navigation = await page.goto(`${suite.server.baseUrl}settings/advanced?section=laboratory`);
+  expect(navigation?.status()).toBe(200);
+  await page.getByRole("button", { name: "Raw", exact: true }).click();
+  return gateway;
+}
+
+async function expectOpenFailure(page: Page, message: string): Promise<void> {
+  const status = page.getByRole("status").filter({ hasText: message });
+  await expect.poll(() => status.count()).toBe(1);
+  await expect.poll(() => status.textContent()).toContain("File path copied to clipboard");
+  await expect.poll(() => status.textContent()).toContain(configPath);
+  await expect
+    .poll(() => page.evaluate(() => Reflect.get(globalThis, "configOpenFileCopied")))
+    .toEqual([configPath]);
+  expect(await page.getByText("Save failed", { exact: true }).count()).toBe(0);
+  expect(await page.getByRole("button", { name: "Retry", exact: true }).count()).toBe(0);
+  expect(await page.locator(".settings-save-indicator").count()).toBe(0);
+}
+
+suite.define(() => {
+  it("announces the path fallback when the host opener returns a failure", async () => {
+    await suite.withPage({ serviceWorkers: "block" }, async ({ page }) => {
+      await openRawSettings(page, {
+        ok: false,
+        path: configPath,
+        error: "No desktop opener is available.",
+      });
+
+      await page.getByRole("button", { name: "Open", exact: true }).click();
+
+      await expectOpenFailure(page, "No desktop opener is available.");
+      if (captureProof) {
+        await mkdir(path.dirname(proofPath), { recursive: true });
+        await page.screenshot({ animations: "disabled", fullPage: true, path: proofPath });
+      }
+    });
+  });
+
+  it("announces the path fallback when the open request rejects", async () => {
+    await suite.withPage({ serviceWorkers: "block" }, async ({ page }) => {
+      const gateway = await openRawSettings(page);
+      await gateway.deferNext("config.openFile");
+
+      await page.getByRole("button", { name: "Open", exact: true }).click();
+      await gateway.waitForRequest("config.openFile");
+      await gateway.rejectDeferred("config.openFile", {
+        code: "UNAVAILABLE",
+        message: "No desktop opener is available.",
+      });
+
+      await expectOpenFailure(page, "No desktop opener is available.");
+    });
+  });
+});
diff --git a/ui/src/lib/config/config-gateway-operations.ts b/ui/src/lib/config/config-gateway-operations.ts
index a0b0a7b2e2be..4babd68d9bbd 100644
--- a/ui/src/lib/config/config-gateway-operations.ts
+++ b/ui/src/lib/config/config-gateway-operations.ts
@@ -5,6 +5,7 @@ import type { ConfigSchemaResponse, ConfigSnapshot } from "../../api/types.ts";
 import { copyToClipboard } from "../clipboard.ts";
 import { serializeConfigForm } from "../config-form-utils.ts";
 import { formatUiError, formatUiExternalText } from "../format-error.ts";
+import { showToast } from "../toast.ts";
 import {
   adoptConfigSetAck,
   applyConfigSnapshot,
@@ -639,6 +640,21 @@ export async function openConfigFile(state: RuntimeConfigState): Promise<void> {
   const isCurrent = () => isCurrentConfigConnection(state, client, connectionEpoch);
   state.lastError = null;
   state.chatError = null;
+  const publishFailure = async (error: string, path?: string | null) => {
+    if (!isCurrent()) {
+      return;
+    }
+    let message = error;
+    if (path) {
+      message += (await copyToClipboard(path))
+        ? `\n\nFile path copied to clipboard: ${path}`
+        : `\n\nFile path: ${path}`;
+    }
+    if (isCurrent()) {
+      state.lastError = formatUiExternalText(message);
+      showToast({ message: state.lastError });
+    }
+  };
   try {
     const res = await client.request<{ ok: boolean; path?: string; error?: string }>(
       "config.openFile",
@@ -648,30 +664,12 @@ export async function openConfigFile(state: RuntimeConfigState): Promise<void> {
       return;
     }
     if (!res.ok) {
-      let errorMessage = formatUiExternalText(res.error, "Failed to open config file");
-      const path = res.path || state.configSnapshot?.path;
-      if (path) {
-        if (await copyToClipboard(path)) {
-          errorMessage += `\n\nFile path copied to clipboard: ${path}`;
-        } else {
-          errorMessage += `\n\nFile path: ${path}`;
-        }
-      }
-      if (isCurrent()) {
-        state.lastError = formatUiExternalText(errorMessage);
-      }
+      await publishFailure(
+        formatUiExternalText(res.error, "Failed to open config file"),
+        res.path || state.configSnapshot?.path,
+      );
     }
   } catch (err) {
-    if (!isCurrent()) {
-      return;
-    }
-    const errorMessage = formatUiError(err);
-    const path = state.configSnapshot?.path;
-    if (path) {
-      await copyToClipboard(path);
-    }
-    if (isCurrent()) {
-      state.lastError = errorMessage;
-    }
+    await publishFailure(formatUiError(err), state.configSnapshot?.path);
   }
 }

From 33a0bea6d0475d353e86ccbea94059c95b41ed90 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 13:48:36 -0700
Subject: [PATCH 092/124] test(agents): cover configured bundle MCP request
 timeouts (#127529)

Adopted from Microsoft's Lobster patch 0042 via the
giodl73-repo/lobster-plugins-and-patches upstream candidate
(source commit e9f84234ebdf, blob 8e753747babe).
---
 src/agents/agent-bundle-mcp-runtime.test.ts | 76 ++++++++++++++++++++-
 1 file changed, 75 insertions(+), 1 deletion(-)

diff --git a/src/agents/agent-bundle-mcp-runtime.test.ts b/src/agents/agent-bundle-mcp-runtime.test.ts
index 59d9e6d5245a..b655d6ef5134 100644
--- a/src/agents/agent-bundle-mcp-runtime.test.ts
+++ b/src/agents/agent-bundle-mcp-runtime.test.ts
@@ -339,7 +339,8 @@ function handle(message) {
     }
     void (async () => {
       await waitForPath(callToolReleasePath);
-      setTimeout(() => {
+      log("delay tools/call " + callToolDelayMs);
+      pendingTimer = setTimeout(() => {
         send({
           jsonrpc: "2.0",
           id: message.id,
@@ -1189,6 +1190,79 @@ describe("session MCP runtime", () => {
     }
   });
 
+  it("uses the configured request timeout instead of the connection timeout for delayed MCP tools/list", async () => {
+    const tempDir = tempDirTracker.make("bundle-mcp-configured-listtools-");
+    const serverPath = path.join(tempDir, "configured-list-tools.mjs");
+    const logPath = path.join(tempDir, "server.log");
+    await writeListToolsMcpServer({
+      filePath: serverPath,
+      logPath,
+      delayMs: 2_000,
+    });
+
+    const runtime = await getOrCreateSessionMcpRuntime({
+      sessionId: "session-configured-listtools-timeout",
+      sessionKey: "agent:test:session-configured-listtools-timeout",
+      workspaceDir: "/workspace",
+      cfg: {
+        mcp: {
+          servers: {
+            configuredListTools: {
+              command: process.execPath,
+              args: [serverPath],
+              connectionTimeoutMs: 1_000,
+              requestTimeoutMs: 4_000,
+            },
+          },
+        },
+      },
+    });
+
+    try {
+      const catalog = await runtime.getCatalog();
+      expect(catalog.tools.map((tool) => tool.toolName)).toEqual(["slow_tool"]);
+      await expect(fs.readFile(logPath, "utf8")).resolves.toContain("delay tools/list 2000");
+    } finally {
+      await runtime.dispose();
+    }
+  });
+
+  it("rejects delayed MCP tools/call responses that exceed the configured request timeout", async () => {
+    const tempDir = tempDirTracker.make("bundle-mcp-call-timeout-");
+    const serverPath = path.join(tempDir, "slow-tool-call.mjs");
+    const logPath = path.join(tempDir, "server.log");
+    await writeListToolsMcpServer({
+      filePath: serverPath,
+      logPath,
+      callToolDelayMs: 1_500,
+    });
+
+    const runtime = await getOrCreateSessionMcpRuntime({
+      sessionId: "session-tool-call-timeout",
+      sessionKey: "agent:test:session-tool-call-timeout",
+      workspaceDir: "/workspace",
+      cfg: {
+        mcp: {
+          servers: {
+            slowToolCall: {
+              command: process.execPath,
+              args: [serverPath],
+              requestTimeoutMs: 250,
+            },
+          },
+        },
+      },
+    });
+
+    try {
+      await runtime.getCatalog();
+      await expect(runtime.callTool("slowToolCall", "slow_tool", {})).rejects.toThrow(/timed out/i);
+      await waitForFileText(logPath, "delay tools/call 1500", LIST_TOOLS_SERVER_LOG_TIMEOUT_MS);
+    } finally {
+      await runtime.dispose();
+    }
+  });
+
   it("times out default-config hung bundle MCP tools/list using the internal catalog timeout", async () => {
     const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "bundle-mcp-listtools-timeout-"));
     const serverPath = path.join(tempDir, "hanging-list-tools.mjs");

From 47d21dc3c695484a0b40fcebefaecf0203cf4794 Mon Sep 17 00:00:00 2001
From: Ben Badejo <188106718+bdjben@users.noreply.github.com>
Date: Fri, 21 Aug 2026 23:54:01 +0300
Subject: [PATCH 093/124] fix(matrix): gateway fails to start when legacy
 credentials differ (#124893)

* fix(matrix): converge differing credential migration

* test(matrix): split doctor credential migrations

---------

Co-authored-by: Benjamin Badejo <ben@benbadejo.com>
---
 .../doctor-contract-api.credentials.test.ts   | 199 ++++++++++++++++++
 extensions/matrix/doctor-contract-api.test.ts |  84 --------
 extensions/matrix/doctor-contract-api.ts      |  10 +-
 3 files changed, 206 insertions(+), 87 deletions(-)
 create mode 100644 extensions/matrix/doctor-contract-api.credentials.test.ts

diff --git a/extensions/matrix/doctor-contract-api.credentials.test.ts b/extensions/matrix/doctor-contract-api.credentials.test.ts
new file mode 100644
index 000000000000..96c1684b9239
--- /dev/null
+++ b/extensions/matrix/doctor-contract-api.credentials.test.ts
@@ -0,0 +1,199 @@
+// Matrix tests cover credential-state migrations owned by the doctor contract.
+import fs from "node:fs";
+import path from "node:path";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import type {
+  OpenKeyedStoreOptions,
+  PluginStateKeyedStore,
+} from "openclaw/plugin-sdk/plugin-state-runtime";
+import {
+  createPluginStateKeyedStoreForTests,
+  getPluginStateCapacityForTests,
+  importPluginStateEntriesForDoctorForTests,
+  resetPluginStateStoreForTests,
+} from "openclaw/plugin-sdk/plugin-state-test-runtime";
+import type { PluginDoctorStateMigrationContext } from "openclaw/plugin-sdk/runtime-doctor-migrations";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { stateMigrations } from "./doctor-contract-api.js";
+import {
+  MATRIX_CREDENTIALS_MAX_ENTRIES,
+  MATRIX_CREDENTIALS_NAMESPACE,
+  matrixCredentialsStoreKey,
+  type MatrixCredentialStateRecord,
+  type MatrixStoredCredentialRecord,
+} from "./src/matrix/credentials-state.js";
+import { installMatrixTestRuntime } from "./src/test-runtime.js";
+import { useAutoCleanupTempDirTracker } from "./test-support.js";
+
+function createContext(env?: NodeJS.ProcessEnv): PluginDoctorStateMigrationContext {
+  return {
+    getPluginStateCapacity() {
+      return getPluginStateCapacityForTests("matrix", env);
+    },
+    importPluginStateEntries(options, entries) {
+      importPluginStateEntriesForDoctorForTests("matrix", options, entries);
+    },
+    openPluginStateKeyedStore: <T>(options: OpenKeyedStoreOptions): PluginStateKeyedStore<T> =>
+      createPluginStateKeyedStoreForTests<T>("matrix", options),
+  };
+}
+
+function createMigrationParams(stateDir: string) {
+  const env = { OPENCLAW_STATE_DIR: stateDir };
+  return {
+    config: {} as OpenClawConfig,
+    env,
+    stateDir,
+    oauthDir: path.join(stateDir, "oauth"),
+    context: createContext(env),
+  };
+}
+
+function migrationById(id: string) {
+  const migration = stateMigrations.find((entry) => entry.id === id);
+  if (!migration) {
+    throw new Error(`missing migration ${id}`);
+  }
+  return migration;
+}
+
+describe("matrix doctor credential state migrations", () => {
+  const tempDirs = useAutoCleanupTempDirTracker(afterEach);
+
+  beforeEach(() => {
+    resetPluginStateStoreForTests();
+    installMatrixTestRuntime();
+  });
+
+  afterEach(() => {
+    resetPluginStateStoreForTests();
+  });
+
+  it("imports account credentials into SQLite before archiving the JSON", async () => {
+    const stateDir = tempDirs.make("openclaw-matrix-doctor-");
+    const credentialsDir = path.join(stateDir, "credentials", "matrix");
+    const filePath = path.join(credentialsDir, "credentials-ops.json");
+    const credentials = {
+      homeserver: "https://matrix.example.org",
+      userId: "@bot:example.org",
+      accessToken: "secret-token",
+      deviceId: "DEVICE123",
+      createdAt: "2026-07-01T12:00:00.000Z",
+      lastUsedAt: "2026-07-02T12:00:00.000Z",
+    };
+    fs.mkdirSync(credentialsDir, { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(credentials));
+    const migration = migrationById("matrix-credentials-json-to-plugin-state");
+    const params = createMigrationParams(stateDir);
+
+    await expect(migration.detectLegacyState(params)).resolves.toEqual({
+      preview: ["Matrix credential JSON can migrate to SQLite (1 file)"],
+    });
+    const result = await migration.migrateLegacyState(params);
+
+    expect(result.warnings).toEqual([]);
+    expect(result.changes).toEqual([
+      "Migrated Matrix credentials for account ops to SQLite",
+      expect.stringContaining("Archived Matrix credentials legacy source"),
+    ]);
+    const store = params.context.openPluginStateKeyedStore<MatrixStoredCredentialRecord>({
+      namespace: MATRIX_CREDENTIALS_NAMESPACE,
+      maxEntries: MATRIX_CREDENTIALS_MAX_ENTRIES,
+      overflowPolicy: "reject-new",
+    });
+    await expect(store.lookup(matrixCredentialsStoreKey("ops"))).resolves.toEqual({
+      accountId: "ops",
+      ...credentials,
+    });
+    expect(fs.existsSync(`${filePath}.migrated`)).toBe(true);
+  });
+
+  it("archives legacy credentials without restoring an explicitly cleared account", async () => {
+    const stateDir = tempDirs.make("openclaw-matrix-doctor-");
+    const credentialsDir = path.join(stateDir, "credentials", "matrix");
+    const filePath = path.join(credentialsDir, "credentials-ops.json");
+    fs.mkdirSync(credentialsDir, { recursive: true });
+    fs.writeFileSync(
+      filePath,
+      JSON.stringify({
+        homeserver: "https://matrix.example.org",
+        userId: "@bot:example.org",
+        accessToken: "legacy-token",
+        createdAt: "2026-07-01T12:00:00.000Z",
+      }),
+    );
+    const params = createMigrationParams(stateDir);
+    const credentialStore = params.context.openPluginStateKeyedStore<MatrixCredentialStateRecord>({
+      namespace: MATRIX_CREDENTIALS_NAMESPACE,
+      maxEntries: MATRIX_CREDENTIALS_MAX_ENTRIES,
+      overflowPolicy: "reject-new",
+    });
+    await credentialStore.register(matrixCredentialsStoreKey("ops"), {
+      accountId: "ops",
+      kind: "revoked",
+      revokedAt: "2026-07-02T12:00:00.000Z",
+    });
+
+    const result = await migrationById(
+      "matrix-credentials-json-to-plugin-state",
+    ).migrateLegacyState(params);
+
+    expect(result.warnings).toEqual([]);
+    expect(result.changes).toEqual([
+      "Archived revoked Matrix credential legacy source for account ops",
+      expect.stringContaining("Archived Matrix credentials legacy source"),
+    ]);
+    expect(fs.existsSync(`${filePath}.migrated`)).toBe(true);
+  });
+
+  it("keeps canonical SQLite credentials and archives a differing legacy source", async () => {
+    const stateDir = tempDirs.make("openclaw-matrix-doctor-");
+    const credentialsDir = path.join(stateDir, "credentials", "matrix");
+    const filePath = path.join(credentialsDir, "credentials-agent1.json");
+    fs.mkdirSync(credentialsDir, { recursive: true });
+    fs.writeFileSync(
+      filePath,
+      JSON.stringify({
+        homeserver: "https://matrix.example.org",
+        userId: "@agent1:example.org",
+        accessToken: "legacy-token",
+        deviceId: "LEGACYDEVICE",
+        createdAt: "2026-07-02T12:00:00.000Z",
+      }),
+    );
+    const params = createMigrationParams(stateDir);
+    const credentialStore = params.context.openPluginStateKeyedStore<MatrixCredentialStateRecord>({
+      namespace: MATRIX_CREDENTIALS_NAMESPACE,
+      maxEntries: MATRIX_CREDENTIALS_MAX_ENTRIES,
+      overflowPolicy: "reject-new",
+    });
+    const canonical: MatrixStoredCredentialRecord = {
+      accountId: "agent1",
+      homeserver: "https://matrix.example.org",
+      userId: "@agent1:example.org",
+      accessToken: "canonical-token",
+      deviceId: "CANONICALDEVICE",
+      createdAt: "2026-07-01T12:00:00.000Z",
+    };
+    await credentialStore.register(matrixCredentialsStoreKey("agent1"), canonical);
+
+    const result = await migrationById(
+      "matrix-credentials-json-to-plugin-state",
+    ).migrateLegacyState(params);
+
+    expect(result.warnings).toEqual([]);
+    expect(result.changes).toEqual([
+      "Kept existing Matrix credentials for account agent1",
+      expect.stringContaining("Archived Matrix credentials legacy source"),
+    ]);
+    await expect(credentialStore.lookup(matrixCredentialsStoreKey("agent1"))).resolves.toEqual(
+      canonical,
+    );
+    expect(fs.existsSync(filePath)).toBe(false);
+    expect(fs.existsSync(`${filePath}.migrated`)).toBe(true);
+    expect(JSON.parse(fs.readFileSync(`${filePath}.migrated`, "utf8"))).toMatchObject({
+      accessToken: "legacy-token",
+      deviceId: "LEGACYDEVICE",
+    });
+  });
+});
diff --git a/extensions/matrix/doctor-contract-api.test.ts b/extensions/matrix/doctor-contract-api.test.ts
index 628f9c0bac23..fc04f60dee67 100644
--- a/extensions/matrix/doctor-contract-api.test.ts
+++ b/extensions/matrix/doctor-contract-api.test.ts
@@ -25,13 +25,6 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { stateMigrations } from "./doctor-contract-api.js";
 import { SqliteBackedMatrixSyncStore } from "./src/matrix/client/file-sync-store.js";
 import { openMatrixStorageMetaStoreOptions } from "./src/matrix/client/storage.js";
-import {
-  MATRIX_CREDENTIALS_MAX_ENTRIES,
-  MATRIX_CREDENTIALS_NAMESPACE,
-  matrixCredentialsStoreKey,
-  type MatrixCredentialStateRecord,
-  type MatrixStoredCredentialRecord,
-} from "./src/matrix/credentials-state.js";
 import {
   MATRIX_IDB_SNAPSHOT_FILENAME,
   MATRIX_RECOVERY_KEY_FILENAME,
@@ -104,83 +97,6 @@ describe("matrix doctor contract state migrations", () => {
     resetPluginStateStoreForTests();
   });
 
-  it("imports account credentials into SQLite before archiving the JSON", async () => {
-    const stateDir = tempDirs.make("openclaw-matrix-doctor-");
-    const credentialsDir = path.join(stateDir, "credentials", "matrix");
-    const filePath = path.join(credentialsDir, "credentials-ops.json");
-    const credentials = {
-      homeserver: "https://matrix.example.org",
-      userId: "@bot:example.org",
-      accessToken: "secret-token",
-      deviceId: "DEVICE123",
-      createdAt: "2026-07-01T12:00:00.000Z",
-      lastUsedAt: "2026-07-02T12:00:00.000Z",
-    };
-    fs.mkdirSync(credentialsDir, { recursive: true });
-    fs.writeFileSync(filePath, JSON.stringify(credentials));
-    const migration = migrationById("matrix-credentials-json-to-plugin-state");
-    const params = createMigrationParams(stateDir);
-
-    await expect(migration.detectLegacyState(params)).resolves.toEqual({
-      preview: ["Matrix credential JSON can migrate to SQLite (1 file)"],
-    });
-    const result = await migration.migrateLegacyState(params);
-
-    expect(result.warnings).toEqual([]);
-    expect(result.changes).toEqual([
-      "Migrated Matrix credentials for account ops to SQLite",
-      expect.stringContaining("Archived Matrix credentials legacy source"),
-    ]);
-    const store = params.context.openPluginStateKeyedStore<MatrixStoredCredentialRecord>({
-      namespace: MATRIX_CREDENTIALS_NAMESPACE,
-      maxEntries: MATRIX_CREDENTIALS_MAX_ENTRIES,
-      overflowPolicy: "reject-new",
-    });
-    await expect(store.lookup(matrixCredentialsStoreKey("ops"))).resolves.toEqual({
-      accountId: "ops",
-      ...credentials,
-    });
-    expect(fs.existsSync(`${filePath}.migrated`)).toBe(true);
-  });
-
-  it("archives legacy credentials without restoring an explicitly cleared account", async () => {
-    const stateDir = tempDirs.make("openclaw-matrix-doctor-");
-    const credentialsDir = path.join(stateDir, "credentials", "matrix");
-    const filePath = path.join(credentialsDir, "credentials-ops.json");
-    fs.mkdirSync(credentialsDir, { recursive: true });
-    fs.writeFileSync(
-      filePath,
-      JSON.stringify({
-        homeserver: "https://matrix.example.org",
-        userId: "@bot:example.org",
-        accessToken: "legacy-token",
-        createdAt: "2026-07-01T12:00:00.000Z",
-      }),
-    );
-    const params = createMigrationParams(stateDir);
-    const credentialStore = params.context.openPluginStateKeyedStore<MatrixCredentialStateRecord>({
-      namespace: MATRIX_CREDENTIALS_NAMESPACE,
-      maxEntries: MATRIX_CREDENTIALS_MAX_ENTRIES,
-      overflowPolicy: "reject-new",
-    });
-    await credentialStore.register(matrixCredentialsStoreKey("ops"), {
-      accountId: "ops",
-      kind: "revoked",
-      revokedAt: "2026-07-02T12:00:00.000Z",
-    });
-
-    const result = await migrationById(
-      "matrix-credentials-json-to-plugin-state",
-    ).migrateLegacyState(params);
-
-    expect(result.warnings).toEqual([]);
-    expect(result.changes).toEqual([
-      "Archived revoked Matrix credential legacy source for account ops",
-      expect.stringContaining("Archived Matrix credentials legacy source"),
-    ]);
-    expect(fs.existsSync(`${filePath}.migrated`)).toBe(true);
-  });
-
   it("migrates legacy sync cache JSON to SQLite plugin state", async () => {
     const stateDir = tempDirs.make("openclaw-matrix-doctor-");
     const storageRootDir = path.join(
diff --git a/extensions/matrix/doctor-contract-api.ts b/extensions/matrix/doctor-contract-api.ts
index 524d6bf9f9a8..9cfde279ee9f 100644
--- a/extensions/matrix/doctor-contract-api.ts
+++ b/extensions/matrix/doctor-contract-api.ts
@@ -270,9 +270,13 @@ export const stateMigrations: PluginDoctorStateMigration[] = [
         }
         const existing = normalizeMatrixStoredCredentials(stored, source.accountId);
         if (existing && JSON.stringify(existing) !== JSON.stringify(credentials)) {
-          warnings.push(
-            `Kept existing Matrix credentials for account ${source.accountId}; left differing legacy source in place`,
-          );
+          changes.push(`Kept existing Matrix credentials for account ${source.accountId}`);
+          await archiveLegacyStateSource({
+            filePath: source.filePath,
+            label: "Matrix credentials",
+            changes,
+            warnings,
+          });
           continue;
         }
         if (!existing) {

From 5b67b61964b91357e981aa56e4848a037c451929 Mon Sep 17 00:00:00 2001
From: Hannes Rudolph <hrudolph@gmail.com>
Date: Fri, 21 Aug 2026 14:57:40 -0600
Subject: [PATCH 094/124] feat(dashboard): let widgets run granted actions and
 open links (#127315)

---
 docs/tools/show-widget.md                     |  6 +++++-
 docs/web/dashboard-architecture.md            | 13 ++++++++-----
 src/agents/sandbox-host.ts                    |  9 ++++++++-
 src/canvas/widget-tool.test.ts                | 10 ++++++++--
 src/canvas/widget-tool.ts                     |  2 +-
 src/canvas/wrap.ts                            |  7 +++++--
 src/gateway/mcp-app-sandbox-http.test.ts      |  6 +++++-
 .../board/board-view.test-support.ts          |  6 +++++-
 ui/src/components/board/board-view.test.ts    | 14 +++++++++-----
 ui/src/components/board/board-widget-frame.ts |  5 ++++-
 ui/src/lib/board/widget-bridge.test.ts        | 19 ++++++++++++++++++-
 ui/src/lib/board/widget-bridge.ts             | 12 ++++++++++++
 ui/src/lib/board/widget-sandbox-host.test.ts  |  7 ++++++-
 ui/src/lib/board/widget-sandbox-host.ts       |  9 ++++++++-
 14 files changed, 102 insertions(+), 23 deletions(-)

diff --git a/docs/tools/show-widget.md b/docs/tools/show-widget.md
index 73191e1960ce..3586a2f02887 100644
--- a/docs/tools/show-widget.md
+++ b/docs/tools/show-widget.md
@@ -133,13 +133,17 @@ Accepted prompts appear in the transcript as regular user messages and start a n
 
 ## Dashboard capabilities
 
-Pinned widgets can use one ticket-bound host API after the operator reviews the declaration shown on the pending card:
+Pinned widgets expose one ticket-bound host API. Calls that require declared capabilities work only after the operator reviews the declaration shown on the pending card:
 
+- `openclaw.host.controlUiBaseUrl` exposes the Control UI origin plus its configured base path after the dashboard host initializes. It is `null` before initialization and outside the dashboard, so read it in the link's click handler rather than when the widget script first runs.
 - `openclaw.prompt.send(text)` requires transient user activation and posts a visible composer message. Declaring and receiving the `prompt` tool grant skips the extra per-click confirmation; validation, focus checks, and rate limits still apply.
 - `openclaw.state.emit(payload)` adds a session notice. Payloads are capped at 8 KiB, and identical client emissions within five seconds are coalesced.
 - `openclaw.data.read(bindingId, params?)` resolves only at the Gateway. Grantable bindings are `sessions.list`, `usage.status`, `usage.cost`, `cron.list`, `cron.status`, `agents.list`, and `health`.
+- `openclaw.action.run(actionId, params?)` invokes an operator-granted plugin dashboard action verb through its write-scoped Gateway method.
 - `openclaw.cron.trigger(jobId)` runs an existing job now only when the exact `cron.trigger:<jobId>` capability was granted.
 
+Links are ordinary user navigation, not a granted host capability. Rendered widgets can open user-clicked links in a new tab; use `target="_blank"` with `rel="noopener noreferrer"` so the dashboard stays open and the destination cannot retain an opener reference.
+
 Network access is separate from host tools. Put exact HTTPS origins in `capabilities.netOrigins`; after approval, only those origins enter the widget's `connect-src`. Wildcards, credentials, paths, query strings, and undeclared origins remain blocked. A literal port is allowed only when it is part of the declared origin.
 
 ## Security and storage
diff --git a/docs/web/dashboard-architecture.md b/docs/web/dashboard-architecture.md
index 1d301b818ee1..1dbb96f9e884 100644
--- a/docs/web/dashboard-architecture.md
+++ b/docs/web/dashboard-architecture.md
@@ -165,6 +165,7 @@ Shared infrastructure underneath (this is where the simplification lands):
   - `openclaw.state.emit` — tier 1 session notices (coalesced, size-capped)
   - `openclaw.data.read` — parameterized read-only bindings (existing
     allowlisted read RPC set), resolved gateway-side
+  - `openclaw.action.run` — tier 3 plugin-owned automation
   - `openclaw.cron.trigger` — tier 3 automation
 - **`net` = CSP.** Network reach uses the already-shipped per-widget CSP
   declaration (`connect-src` origins) — the self-updating weather widget
@@ -175,12 +176,14 @@ Shared infrastructure underneath (this is where the simplification lands):
   `pending` on the board: a placeholder card lists them human-readably with
   one-tap **Allow**/**Reject**. Grants are per widget name; for `html` widgets
   they are byte-frozen (sha256), and changed bytes keep the grant only if the
-  declaration shrank.
+  declaration shrank. User-clicked links are ordinary navigation rather than a
+  grant capability and open in a new tab for every rendered widget.
 - **Authoring shim.** The document wrapper injects `window.openclaw.prompt`,
-  `window.openclaw.state`, `window.openclaw.data`, and `window.openclaw.cron`
-  as the stable author API. Dashboard calls share one view-ticket-bound
-  request channel; size reporting and theme tokens remain separate host
-  notifications.
+  `window.openclaw.state`, `window.openclaw.data`, `window.openclaw.action`,
+  `window.openclaw.cron`, and the host-provided
+  `window.openclaw.host.controlUiBaseUrl` as the stable author API. Dashboard
+  calls share one view-ticket-bound request channel; size reporting and theme
+  tokens remain separate host notifications.
 
 ### Plugin capability declarations
 
diff --git a/src/agents/sandbox-host.ts b/src/agents/sandbox-host.ts
index eacab846e776..d94df17becd8 100644
--- a/src/agents/sandbox-host.ts
+++ b/src/agents/sandbox-host.ts
@@ -230,7 +230,14 @@ export function buildSandboxHostProxyHtml(csp?: SandboxHostCsp): string {
   }
   const createInner = () => {
     const frame = document.createElement("iframe");
-    frame.setAttribute("sandbox", "allow-scripts allow-forms");
+    // Nested sandbox restrictions compose with the host iframe. The inner
+    // document must declare popup support so a granted outer widget can open
+    // user-clicked links, while ungranted widgets remain blocked by the outer
+    // frame's stricter sandbox.
+    frame.setAttribute(
+      "sandbox",
+      "allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox",
+    );
     return frame;
   };
   let inner = createInner();
diff --git a/src/canvas/widget-tool.test.ts b/src/canvas/widget-tool.test.ts
index 7b645f5ccfb9..12e1667033c8 100644
--- a/src/canvas/widget-tool.test.ts
+++ b/src/canvas/widget-tool.test.ts
@@ -248,6 +248,9 @@ describe("show_widget", () => {
   it("keeps widget documents from duplicating host-owned metadata and controls", () => {
     const description = createShowWidgetTool().description;
 
+    expect(description).toContain("openclaw.host.controlUiBaseUrl");
+    expect(description).toContain("read it at click time");
+    expect(description).toContain('target="_blank" and rel="noopener noreferrer"');
     expect(description).toContain("`title` is host metadata");
     expect(description).toContain("Start directly with content");
     expect(description).toContain("do not repeat the title");
@@ -541,11 +544,13 @@ describe("show_widget", () => {
       '<SvG viewBox="0 0 10 10"><circle r="4" /></SvG>',
     );
 
-    expect(Buffer.byteLength(html)).toBe(13493);
+    expect(Buffer.byteLength(html)).toBe(13859);
     expect(createHash("sha256").update(html).digest("hex")).toBe(
-      "e50212b277bc75dc07a1c6c46cc313ff8f5cbfe261211b12d1714ad9d6b8c912",
+      "a3d6c52c6b19498b1041a3e2c0feac20b234f6497cf3d41c8783feba3ae47dcf",
     );
     expect(html).toContain("openclaw:widget-host-init-ack");
+    expect(html).toContain("controlUiBaseUrl");
+    expect(html).toContain('define(host,"controlUiBaseUrl"');
     expect(html).toContain("else push.call(waiting,{send,reject})");
     expect(html).toContain("else push.call(promptWaiting,{send,inline,reject})");
     expect(html).toContain("openclaw:widget-prompt-host-ready");
@@ -1019,6 +1024,7 @@ describe("show_widget", () => {
     expect(html).toContain("prompt:freeze({send:sendPrompt})");
     expect(html).toContain('state:freeze({emit:payload=>request("state.emit"');
     expect(html).toContain('data:freeze({read:(bindingId,params)=>request("data.read"');
+    expect(html).toContain('action:freeze({run:(action,params)=>request("action.run"');
     expect(html).toContain('cron:freeze({trigger:jobId=>request("cron.trigger"');
     expect(html).toContain("navigator.userActivation");
     expect(html).toContain("c.port1.postMessage.bind(c.port1)");
diff --git a/src/canvas/widget-tool.ts b/src/canvas/widget-tool.ts
index 9c6552cc1e34..0362a10a74cc 100644
--- a/src/canvas/widget-tool.ts
+++ b/src/canvas/widget-tool.ts
@@ -273,7 +273,7 @@ export function createShowWidgetTool(options: ShowWidgetToolOptions = {}): AnyAg
   return {
     label: "Show Widget",
     name: "show_widget",
-    description: `Visual helps? Make widget. Do not wait for ask. Keep one ad hoc non-code visualization inline. Pin only for an explicit dashboard request or multiple non-code visualizations. Use for comparisons, trends, timelines, flows, hierarchies, dashboards, status, progress, layouts, and choices. Text clearer? Skip. Show a widget on the user's current surface; kind defaults to html${advertisedRegisteredKinds.length ? ` and registered kinds are ${advertisedRegisteredKinds.join(", ")}` : ""}. ${inlineHostEnabled ? "Set pin=true to also place it on this session's dashboard" : "Inline hosting is disabled; set pin=true to place it on this session's dashboard"}; use name for a stable widget id, tab for a tab slug, size sm|md|lg|xl|full, presentation.frame card|full-bleed|frameless, and after for a sibling widget anchor. Pinned widgets may declare capabilities.netOrigins and capabilities.tools for operator approval. HTML widgets are self-contained HTML or SVG. Dashboard host APIs: openclaw.prompt.send(text), openclaw.state.emit(payload), openclaw.data.read(bindingId, params?), and openclaw.cron.trigger(jobId). \`title\` is host metadata. Start directly with content; do not repeat the title or recreate dashboard chrome. HTML is pre-themed with --surface --card --elevated --text --text-strong --muted --border --border-strong --accent --accent-fill --accent-fg --ok --warn --danger --info --radius --font-body --font-mono.${presenterPrompt}`,
+    description: `Visual helps? Make widget. Do not wait for ask. Keep one ad hoc non-code visualization inline. Pin only for an explicit dashboard request or multiple non-code visualizations. Use for comparisons, trends, timelines, flows, hierarchies, dashboards, status, progress, layouts, and choices. Text clearer? Skip. Show a widget on the user's current surface; kind defaults to html${advertisedRegisteredKinds.length ? ` and registered kinds are ${advertisedRegisteredKinds.join(", ")}` : ""}. ${inlineHostEnabled ? "Set pin=true to also place it on this session's dashboard" : "Inline hosting is disabled; set pin=true to place it on this session's dashboard"}; use name for a stable widget id, tab for a tab slug, size sm|md|lg|xl|full, presentation.frame card|full-bleed|frameless, and after for a sibling widget anchor. Pinned widgets may declare capabilities.netOrigins and capabilities.tools for operator approval. HTML widgets are self-contained HTML or SVG. Dashboard host APIs: openclaw.prompt.send(text), openclaw.state.emit(payload), openclaw.data.read(bindingId, params?), openclaw.action.run(actionId, params?), and openclaw.cron.trigger(jobId). openclaw.host.controlUiBaseUrl is the Control UI origin plus base path after dashboard host initialization, otherwise null; read it at click time. Open links in a new tab with target="_blank" and rel="noopener noreferrer". \`title\` is host metadata. Start directly with content; do not repeat the title or recreate dashboard chrome. HTML is pre-themed with --surface --card --elevated --text --text-strong --muted --border --border-strong --accent --accent-fill --accent-fg --ok --warn --danger --info --radius --font-body --font-mono.${presenterPrompt}`,
     parameters: createShowWidgetToolSchema(kinds, explicitPresenters),
     ...(currentChannelPresenter ? {} : { requiredClientCaps: SHOW_WIDGET_REQUIRED_CLIENT_CAPS }),
     execute: async (_toolCallId, args) => {
diff --git a/src/canvas/wrap.ts b/src/canvas/wrap.ts
index 600d3f9b0b95..ba814128c2fc 100644
--- a/src/canvas/wrap.ts
+++ b/src/canvas/wrap.ts
@@ -127,11 +127,12 @@ export function buildWidgetDocument(
     "if(d&&d.get)act=d.get.bind(ua);}catch{}" +
     'post({type:"openclaw:widget-prompt-offer"},"*",[c.port2]);' +
     'post({type:"openclaw:widget-bridge-port-offer"},"*",[b.port2]);' +
-    "let ticket=null;let sequence=0;let hostInitExpired=false;const pending=new Map();const waiting=[];" +
+    "let ticket=null;let controlUiBaseUrl=null;let sequence=0;let hostInitExpired=false;const pending=new Map();const waiting=[];" +
     'const initTimer=later(()=>{hostInitExpired=true;while(waiting.length){const entry=shift.call(waiting);if(entry)entry.reject(new ErrorCtor("widget host capabilities unavailable"));}' +
     'while(promptWaiting.length){const entry=shift.call(promptWaiting);if(entry)entry.reject(new ErrorCtor("widget prompt host unavailable"));}},5000);' +
     'b.port1.addEventListener("message",event=>{const data=event.data;' +
     'if(data?.type==="openclaw:widget-host-init"&&typeof data.ticket==="string"){ticket=data.ticket;' +
+    'const base=data.controlUiBaseUrl;controlUiBaseUrl=typeof base==="string"&&/^https?:\\/\\//.test(base)?base:null;' +
     'bridgePost({type:"openclaw:widget-host-init-ack",ticket});cancel(initTimer);' +
     "while(waiting.length){const entry=shift.call(waiting);if(entry)entry.send();}" +
     "while(promptWaiting.length){const entry=shift.call(promptWaiting);if(entry)entry.send();}return;}" +
@@ -150,9 +151,11 @@ export function buildWidgetDocument(
     'const inline=()=>{promptPost({type:"openclaw:widget-prompt",prompt:value});resolve(true);};' +
     'if(inlinePromptReady)inline();else if(hostInitExpired)reject(new ErrorCtor("widget prompt host unavailable"));' +
     "else push.call(promptWaiting,{send,inline,reject});});};" +
-    "const api=freeze({" +
+    'const host={};define(host,"controlUiBaseUrl",{enumerable:true,get:()=>controlUiBaseUrl});freeze(host);' +
+    "const api=freeze({host," +
     'prompt:freeze({send:sendPrompt}),state:freeze({emit:payload=>request("state.emit",{payload})}),' +
     'data:freeze({read:(bindingId,params)=>request("data.read",{bindingId:stringify(bindingId),params})}),' +
+    'action:freeze({run:(action,params)=>request("action.run",{action:stringify(action),params:params===undefined?{}:params})}),' +
     'cron:freeze({trigger:jobId=>request("cron.trigger",{jobId:stringify(jobId)})})});' +
     'define(window,"openclaw",{value:api,writable:false,configurable:false});' +
     "window.sendPrompt=text=>{void sendPrompt(text);};" +
diff --git a/src/gateway/mcp-app-sandbox-http.test.ts b/src/gateway/mcp-app-sandbox-http.test.ts
index 20e8714c4be8..978289e16a98 100644
--- a/src/gateway/mcp-app-sandbox-http.test.ts
+++ b/src/gateway/mcp-app-sandbox-http.test.ts
@@ -59,7 +59,11 @@ describe("MCP App sandbox HTTP origin", () => {
     );
     expect(result.end).toHaveBeenCalledWith(expect.stringContaining("document.referrer"));
     expect(result.end).toHaveBeenCalledWith(expect.stringContaining("sandbox-proxy-ready"));
-    expect(result.end).toHaveBeenCalledWith(expect.stringContaining("allow-scripts allow-forms"));
+    expect(result.end).toHaveBeenCalledWith(
+      expect.stringContaining(
+        "allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox",
+      ),
+    );
     expect(result.end).toHaveBeenCalledWith(
       expect.stringContaining("openclaw:widget-bridge-port-offer"),
     );
diff --git a/ui/src/components/board/board-view.test-support.ts b/ui/src/components/board/board-view.test-support.ts
index 81bd4e997c72..61211c0f21c3 100644
--- a/ui/src/components/board/board-view.test-support.ts
+++ b/ui/src/components/board/board-view.test-support.ts
@@ -61,8 +61,12 @@ export function callbacks(overrides: Partial<BoardViewCallbacks> = {}): BoardVie
   };
 }
 
-export function gatewayContext(client: { request: ReturnType<typeof vi.fn> } | null) {
+export function gatewayContext(
+  client: { request: ReturnType<typeof vi.fn> } | null,
+  basePath = "",
+) {
   return {
+    basePath,
     gateway: {
       connection: { gatewayUrl: "" },
       snapshot: { client },
diff --git a/ui/src/components/board/board-view.test.ts b/ui/src/components/board/board-view.test.ts
index 96c8e14bdd1c..b317ca66d950 100644
--- a/ui/src/components/board/board-view.test.ts
+++ b/ui/src/components/board/board-view.test.ts
@@ -58,6 +58,9 @@ describe("openclaw-board-view", () => {
 
     const frame = view.querySelector("iframe");
     expect(frame?.getAttribute("src")).toContain(":18790/mcp-app-sandbox");
+    expect(frame?.getAttribute("sandbox")).toBe(
+      "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox",
+    );
     expect(frame?.getAttribute("loading")).toBe("eager");
     expect(view.querySelector('[data-test-id="board-widget-error"]')).toBeNull();
   });
@@ -94,7 +97,7 @@ describe("openclaw-board-view", () => {
     const fetchMock = vi.fn(async () => new Response("<!doctype html><p>weather</p>"));
     vi.stubGlobal("fetch", fetchMock);
     const view = await mount({
-      context: gatewayContext({ request: firstRequest }),
+      context: gatewayContext({ request: firstRequest }, "/control"),
       snapshot: snapshot({
         widgets: [
           boardWidget({
@@ -125,7 +128,7 @@ describe("openclaw-board-view", () => {
     });
     await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledOnce());
     const bridgeChannel = new MessageChannel();
-    const initialized = new Promise<void>((resolve) => {
+    const initialized = new Promise<{ controlUiBaseUrl?: string }>((resolve) => {
       bridgeChannel.port2.addEventListener("message", (event) => {
         if (event.data?.type !== "openclaw:widget-host-init") {
           return;
@@ -137,12 +140,13 @@ describe("openclaw-board-view", () => {
           },
           [],
         );
-        resolve();
+        resolve(event.data as { controlUiBaseUrl?: string });
       });
     });
     bridgeChannel.port2.start();
     send({ type: "openclaw:widget-bridge-port-offer" }, [bridgeChannel.port1]);
-    await initialized;
+    const hostInit = await initialized;
+    expect(hostInit.controlUiBaseUrl).toBe(`${window.location.origin}/control`);
     bridgeChannel.port2.postMessage(
       {
         type: "openclaw:widget-bridge-request",
@@ -161,7 +165,7 @@ describe("openclaw-board-view", () => {
     );
 
     const provider = view.parentElement as ReturnType<typeof createApplicationContextProvider>;
-    provider.setContext(gatewayContext({ request: secondRequest }));
+    provider.setContext(gatewayContext({ request: secondRequest }, "/control"));
     await cell.updateComplete;
     bridgeChannel.port2.postMessage(
       {
diff --git a/ui/src/components/board/board-widget-frame.ts b/ui/src/components/board/board-widget-frame.ts
index 0ca201093526..88e89126052d 100644
--- a/ui/src/components/board/board-widget-frame.ts
+++ b/ui/src/components/board/board-widget-frame.ts
@@ -17,6 +17,8 @@ const TICKET_REFRESH_LEAD_MS = 15_000;
 const TICKET_REFRESH_MIN_DELAY_MS = 1_000;
 const TICKET_REFRESH_RETRY_MS = 1_000;
 const TICKET_REFRESH_MAX_RETRY_MS = 30_000;
+const WIDGET_SANDBOX =
+  "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox";
 
 function documentHidden(): boolean {
   return typeof document !== "undefined" && document.visibilityState === "hidden";
@@ -240,7 +242,7 @@ export class BoardWidgetFrameLifecycle {
       return html`
         <iframe
           class="board-widget__frame"
-          sandbox="allow-scripts allow-same-origin allow-forms"
+          sandbox=${WIDGET_SANDBOX}
           referrerpolicy="origin"
           loading="eager"
           title=${widget.title || widget.name}
@@ -402,6 +404,7 @@ export class BoardWidgetFrameLifecycle {
         this.host.context()?.gateway.connection.gatewayUrl ?? "",
         window.location.origin,
       ),
+      controlUiBaseUrl: `${window.location.origin}${this.host.context()?.basePath ?? ""}`,
       client: this.host.context()?.gateway.snapshot.client ?? undefined,
       resolveFrameUrl,
       confirmPrompt: (prompt) => window.confirm(`${t("common.confirm")}:\n\n${prompt}`),
diff --git a/ui/src/lib/board/widget-bridge.test.ts b/ui/src/lib/board/widget-bridge.test.ts
index e66dc107f55c..465ae88ac383 100644
--- a/ui/src/lib/board/widget-bridge.test.ts
+++ b/ui/src/lib/board/widget-bridge.test.ts
@@ -199,12 +199,15 @@ describe("board widget bridge", () => {
     expect(client.request).toHaveBeenCalledTimes(13);
   });
 
-  it("maps read and cron requests to ticket-bound board RPCs", async () => {
+  it("maps read, action, and cron requests to ticket-bound board RPCs", async () => {
     const { controller, client } = setup();
 
     await controller.handle(
       request("data.read", { bindingId: "health", params: { probe: false } }),
     );
+    await controller.handle(
+      request("action.run", { action: "example.resolve", params: { eventId: "event-1" } }),
+    );
     await controller.handle(request("cron.trigger", { jobId: "job-1" }));
 
     expect(client.request).toHaveBeenNthCalledWith(1, "board.data.read", {
@@ -213,9 +216,23 @@ describe("board widget bridge", () => {
       params: { probe: false },
     });
     expect(client.request).toHaveBeenNthCalledWith(2, "board.action", {
+      ticket: "ticket",
+      action: "example.resolve",
+      params: { eventId: "event-1" },
+    });
+    expect(client.request).toHaveBeenNthCalledWith(3, "board.action", {
       ticket: "ticket",
       action: "cron.trigger",
       jobId: "job-1",
     });
   });
+
+  it("rejects non-object action params", async () => {
+    const { controller, client } = setup();
+
+    await expect(
+      controller.handle(request("action.run", { action: "example.resolve", params: "bad" })),
+    ).rejects.toThrow("widget action params are invalid");
+    expect(client.request).not.toHaveBeenCalled();
+  });
 });
diff --git a/ui/src/lib/board/widget-bridge.ts b/ui/src/lib/board/widget-bridge.ts
index 42089c7b1db5..72c0cae4d8ef 100644
--- a/ui/src/lib/board/widget-bridge.ts
+++ b/ui/src/lib/board/widget-bridge.ts
@@ -172,6 +172,18 @@ export class BoardWidgetBridgeController {
           ...(bindingParams ? { params: bindingParams as Record<string, unknown> } : {}),
         });
       }
+      case "action.run": {
+        const action = requiredString(params, "action");
+        const actionParams = params.params;
+        if (actionParams !== undefined && !isRecord(actionParams)) {
+          throw new Error("widget action params are invalid");
+        }
+        return await this.client.request("board.action", {
+          ticket: this.ticket,
+          action,
+          params: actionParams ?? {},
+        });
+      }
       case "cron.trigger":
         return await this.client.request("board.action", {
           ticket: this.ticket,
diff --git a/ui/src/lib/board/widget-sandbox-host.test.ts b/ui/src/lib/board/widget-sandbox-host.test.ts
index f3499a2c55cd..d7301f7b2f50 100644
--- a/ui/src/lib/board/widget-sandbox-host.test.ts
+++ b/ui/src/lib/board/widget-sandbox-host.test.ts
@@ -184,6 +184,7 @@ describe("BoardWidgetSandboxHost", () => {
       sandboxOrigin: "https://sandbox.example",
       sandboxUrl: SANDBOX_URL,
       sourceOrigin: "https://gateway.example",
+      controlUiBaseUrl: "https://control.example/openclaw",
       resolveFrameUrl: () => "/widget",
       confirmPrompt: () => true,
       onFrameUrl: vi.fn(),
@@ -218,7 +219,11 @@ describe("BoardWidgetSandboxHost", () => {
 
     expect(hostMessage).toHaveBeenCalledWith(
       expect.objectContaining({
-        data: { type: "openclaw:widget-host-init", ticket: "ticket" },
+        data: {
+          type: "openclaw:widget-host-init",
+          ticket: "ticket",
+          controlUiBaseUrl: "https://control.example/openclaw",
+        },
       }),
     );
   });
diff --git a/ui/src/lib/board/widget-sandbox-host.ts b/ui/src/lib/board/widget-sandbox-host.ts
index 52a7b90f731f..a196cd2a63b5 100644
--- a/ui/src/lib/board/widget-sandbox-host.ts
+++ b/ui/src/lib/board/widget-sandbox-host.ts
@@ -15,6 +15,7 @@ type BoardWidgetSandboxHostOptions = {
   sandboxOrigin: string;
   sandboxUrl: string;
   sourceOrigin: string;
+  controlUiBaseUrl?: string;
   client?: BoardWidgetBridgeGatewayClient;
   resolveFrameUrl: BoardWidgetFrameUrl;
   confirmPrompt: (text: string) => boolean;
@@ -346,7 +347,13 @@ export class BoardWidgetSandboxHost {
       return;
     }
     this.offeredTicket = ticket;
-    this.bridgePort.postMessage({ type: "openclaw:widget-host-init", ticket }, []);
+    const controlUiBaseUrl = this.options.controlUiBaseUrl?.trim();
+    this.bridgePort.postMessage(
+      controlUiBaseUrl
+        ? { type: "openclaw:widget-host-init", ticket, controlUiBaseUrl }
+        : { type: "openclaw:widget-host-init", ticket },
+      [],
+    );
   }
 
   private async loadDocument(): Promise<void> {

From eb8d90a24645274e17ebb9acacb4801b9fc9fd3d Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 14:09:18 -0700
Subject: [PATCH 095/124] fix(crabbox): decouple lease heartbeat budget from
 renewal cadence (#127559)

* fix(crabbox): decouple lease heartbeat budget from cadence

Give coordinator lease heartbeats an independent 150-second execution budget, capped at half the idle timeout, after production AWS samples reached 107.6 seconds. Preserve the renewal cadence and unrelated lifecycle timeouts while identifying Crabbox v0.44.0 as the first heartbeat-capable release.

* refactor(crabbox): parse profile durations once

requirePositiveDuration already parsed the duration to validate it, then
discarded the result so the caller re-parsed and coerced an Option to a
number without handling undefined. Return the parsed milliseconds instead:
one parse, and no path where a NaN idle timeout reaches the heartbeat
budget.
---
 .../crabbox/src/crabbox-worker-heartbeat.ts   |  4 +--
 .../crabbox/src/crabbox-worker-profile.ts     | 32 ++++++++++++-------
 .../src/crabbox-worker-provider.test.ts       | 24 ++++++++------
 .../crabbox/src/crabbox-worker-provider.ts    |  6 ++--
 .../crabbox/src/crabbox-worker-timeouts.ts    |  2 ++
 5 files changed, 43 insertions(+), 25 deletions(-)

diff --git a/extensions/crabbox/src/crabbox-worker-heartbeat.ts b/extensions/crabbox/src/crabbox-worker-heartbeat.ts
index ceee77f9218d..655b7c321607 100644
--- a/extensions/crabbox/src/crabbox-worker-heartbeat.ts
+++ b/extensions/crabbox/src/crabbox-worker-heartbeat.ts
@@ -1,12 +1,12 @@
 import type { SpawnResult } from "openclaw/plugin-sdk/process-runtime";
 import { crabboxCommandError } from "./crabbox-worker-command-error.js";
 
-const CRABBOX_HEARTBEAT_UPGRADE =
-  "upgrade Crabbox to a release that includes `crabbox heartbeat` (added after v0.43.0)";
+const CRABBOX_HEARTBEAT_UPGRADE = "upgrade Crabbox to v0.44.0 or newer for `crabbox heartbeat`";
 
 type HeartbeatContext = {
   binary: string;
   heartbeatIntervalMs: number;
+  heartbeatTimeoutMs: number;
   id: string;
   idleTimeout: string;
   provider: string;
diff --git a/extensions/crabbox/src/crabbox-worker-profile.ts b/extensions/crabbox/src/crabbox-worker-profile.ts
index 14f3abd35c9f..93d7622e17ad 100644
--- a/extensions/crabbox/src/crabbox-worker-profile.ts
+++ b/extensions/crabbox/src/crabbox-worker-profile.ts
@@ -7,6 +7,7 @@ import {
   type WorkerProfile,
 } from "openclaw/plugin-sdk/plugin-entry";
 import { normalizeOptionalString as nonEmptyString } from "openclaw/plugin-sdk/string-coerce-runtime";
+import { CRABBOX_HEARTBEAT_TIMEOUT_MS } from "./crabbox-worker-timeouts.js";
 
 export { nonEmptyString };
 
@@ -39,6 +40,7 @@ type CrabboxProfile = {
   class: string;
   desktop?: boolean;
   heartbeatIntervalMs: number;
+  heartbeatTimeoutMs: number;
   idleTimeout: string;
   provider: string;
   ttl: string;
@@ -60,14 +62,18 @@ type IsExecutable = (candidate: string) => boolean;
 
 export const CRABBOX_WORKER_PROVIDER_ID = "crabbox";
 
-function requirePositiveDuration(value: unknown, key: string): string {
+function requirePositiveDuration(
+  value: unknown,
+  key: string,
+): { duration: string; milliseconds: number } {
   const duration = nonEmptyString(value);
-  if (!duration || parsePositiveGoDurationNanoseconds(duration) === undefined) {
+  const nanoseconds = duration ? parsePositiveGoDurationNanoseconds(duration) : undefined;
+  if (!duration || nanoseconds === undefined) {
     throw new WorkerProviderError(
       `Crabbox profile ${key} must be a positive Go duration such as 60m`,
     );
   }
-  return duration;
+  return { duration, milliseconds: Number(nanoseconds) / 1_000_000 };
 }
 
 function parsePositiveGoDurationNanoseconds(duration: string): bigint | undefined {
@@ -98,12 +104,7 @@ function parsePositiveGoDurationNanoseconds(duration: string): bigint | undefine
   return total > 0n ? total : undefined;
 }
 
-function heartbeatIntervalMs(idleTimeout: string): number {
-  const idleNanoseconds = parsePositiveGoDurationNanoseconds(idleTimeout);
-  if (idleNanoseconds === undefined) {
-    throw new Error("Crabbox heartbeat requires a positive idle timeout");
-  }
-  const idleTimeoutMs = Number(idleNanoseconds) / 1_000_000;
+function heartbeatIntervalMs(idleTimeoutMs: number): number {
   const referenceIntervalMs = Math.max(5_000, Math.min(60_000, idleTimeoutMs / 3));
   // Crabbox's floor can exceed short accepted timeouts. Keep renewal ahead of
   // coordinator idle expiry without changing the profile contract.
@@ -125,8 +126,11 @@ export function parseCrabboxProfile(profile: WorkerProfile): CrabboxProfile {
   if (!machineClass) {
     throw new WorkerProviderError("Crabbox profile class must be a non-empty string");
   }
-  const ttl = requirePositiveDuration(profile.ttl, "ttl");
-  const idleTimeout = requirePositiveDuration(profile.idleTimeout, "idleTimeout");
+  const { duration: ttl } = requirePositiveDuration(profile.ttl, "ttl");
+  const { duration: idleTimeout, milliseconds: idleTimeoutMs } = requirePositiveDuration(
+    profile.idleTimeout,
+    "idleTimeout",
+  );
   const binaryValue = profile.binary;
   const binary = binaryValue === undefined ? undefined : nonEmptyString(binaryValue);
   if (binaryValue !== undefined && !binary) {
@@ -153,7 +157,11 @@ export function parseCrabboxProfile(profile: WorkerProfile): CrabboxProfile {
     binary,
     class: machineClass,
     desktop,
-    heartbeatIntervalMs: heartbeatIntervalMs(idleTimeout),
+    heartbeatIntervalMs: heartbeatIntervalMs(idleTimeoutMs),
+    heartbeatTimeoutMs: Math.min(
+      CRABBOX_HEARTBEAT_TIMEOUT_MS,
+      Math.max(1, Math.floor(idleTimeoutMs / 2)),
+    ),
     idleTimeout,
     provider,
     setup,
diff --git a/extensions/crabbox/src/crabbox-worker-provider.test.ts b/extensions/crabbox/src/crabbox-worker-provider.test.ts
index 3da9f640ae7c..9d2764888d6c 100644
--- a/extensions/crabbox/src/crabbox-worker-provider.test.ts
+++ b/extensions/crabbox/src/crabbox-worker-provider.test.ts
@@ -1956,20 +1956,25 @@ describe("Crabbox worker provider", () => {
   });
 
   it.each([
-    { idleTimeout: "1s", idleTimeoutMs: 1_000, intervalMs: 500 },
-    { idleTimeout: "2s", idleTimeoutMs: 2_000, intervalMs: 1_000 },
-    { idleTimeout: "5s", idleTimeoutMs: 5_000, intervalMs: 2_500 },
-    { idleTimeout: "12s", idleTimeoutMs: 12_000, intervalMs: 5_000 },
-    { idleTimeout: "30s", idleTimeoutMs: 30_000, intervalMs: 10_000 },
-    { idleTimeout: "6m", idleTimeoutMs: 360_000, intervalMs: 60_000 },
+    { idleTimeout: "1s", idleTimeoutMs: 1_000, intervalMs: 500, timeoutMs: 500 },
+    { idleTimeout: "2s", idleTimeoutMs: 2_000, intervalMs: 1_000, timeoutMs: 1_000 },
+    { idleTimeout: "5s", idleTimeoutMs: 5_000, intervalMs: 2_500, timeoutMs: 2_500 },
+    { idleTimeout: "12s", idleTimeoutMs: 12_000, intervalMs: 5_000, timeoutMs: 6_000 },
+    { idleTimeout: "30s", idleTimeoutMs: 30_000, intervalMs: 10_000, timeoutMs: 15_000 },
+    { idleTimeout: "6m", idleTimeoutMs: 360_000, intervalMs: 60_000, timeoutMs: 150_000 },
+    { idleTimeout: "45m", idleTimeoutMs: 2_700_000, intervalMs: 60_000, timeoutMs: 150_000 },
   ])(
     "heartbeats an active lease every $intervalMs ms for idleTimeout=$idleTimeout",
-    async ({ idleTimeout, idleTimeoutMs, intervalMs }) => {
+    async ({ idleTimeout, idleTimeoutMs, intervalMs, timeoutMs }) => {
       vi.useFakeTimers();
       const calls: string[][] = [];
+      const heartbeatTimeouts: number[] = [];
       const profile = { ...PROFILE, idleTimeout };
-      const provider = providerWithRunner(async (argv) => {
+      const provider = providerWithRunner(async (argv, options) => {
         calls.push(argv);
+        if (argv[1] === "heartbeat") {
+          heartbeatTimeouts.push(options.timeoutMs);
+        }
         return argv[1] === "inspect"
           ? commandResult({ stdout: inspectJson({ sshHostKey: HOST_KEY }) })
           : commandResult();
@@ -1994,6 +1999,7 @@ describe("Crabbox worker provider", () => {
             "--json",
           ],
         ]);
+        expect(heartbeatTimeouts).toEqual([timeoutMs]);
 
         await vi.advanceTimersByTimeAsync(intervalMs - 1);
         expect(heartbeatCalls()).toHaveLength(1);
@@ -2083,7 +2089,7 @@ describe("Crabbox worker provider", () => {
 
       expect(calls.filter((argv) => argv[1] === "heartbeat")).toHaveLength(1);
       expect(warnings).toEqual([
-        `Crabbox heartbeat is unavailable for worker lease ${LEASE_ID}; upgrade Crabbox to a release that includes \`crabbox heartbeat\` (added after v0.43.0); cloud worker machines may be reaped after 60m of coordinator-idle time`,
+        `Crabbox heartbeat is unavailable for worker lease ${LEASE_ID}; upgrade Crabbox to v0.44.0 or newer for \`crabbox heartbeat\`; cloud worker machines may be reaped after 60m of coordinator-idle time`,
       ]);
     } finally {
       await provider.destroy(lease);
diff --git a/extensions/crabbox/src/crabbox-worker-provider.ts b/extensions/crabbox/src/crabbox-worker-provider.ts
index da32883f8c42..606a46a261de 100644
--- a/extensions/crabbox/src/crabbox-worker-provider.ts
+++ b/extensions/crabbox/src/crabbox-worker-provider.ts
@@ -77,7 +77,7 @@ type CrabboxProfile = ReturnType<typeof parseCrabboxProfile>;
 
 type LeaseCommandContext = { binary: string; id: string; provider: string };
 type LeaseHeartbeatContext = LeaseCommandContext &
-  Pick<CrabboxProfile, "heartbeatIntervalMs" | "idleTimeout">;
+  Pick<CrabboxProfile, "heartbeatIntervalMs" | "heartbeatTimeoutMs" | "idleTimeout">;
 type ProvisionInspectContext = Omit<LeaseCommandContext, "id"> & {
   deadline: number;
   inspect: ParsedInspect;
@@ -433,7 +433,7 @@ export function createCrabboxWorkerProvider(
         binary: context.binary,
         runCommand,
         signal,
-        timeoutMs: Math.min(CRABBOX_LIFECYCLE_TIMEOUT_MS, context.heartbeatIntervalMs),
+        timeoutMs: context.heartbeatTimeoutMs,
       }),
     warn,
   });
@@ -466,6 +466,7 @@ export function createCrabboxWorkerProvider(
     return {
       binary: resolveBinary(parsed.binary),
       heartbeatIntervalMs: parsed.heartbeatIntervalMs,
+      heartbeatTimeoutMs: parsed.heartbeatTimeoutMs,
       id: lease.leaseId,
       idleTimeout: parsed.idleTimeout,
       provider: parsed.provider,
@@ -637,6 +638,7 @@ export function createCrabboxWorkerProvider(
       heartbeats.start({
         binary,
         heartbeatIntervalMs: parsed.heartbeatIntervalMs,
+        heartbeatTimeoutMs: parsed.heartbeatTimeoutMs,
         id: leaseId,
         idleTimeout: parsed.idleTimeout,
         provider: parsed.provider,
diff --git a/extensions/crabbox/src/crabbox-worker-timeouts.ts b/extensions/crabbox/src/crabbox-worker-timeouts.ts
index 7ab19458240a..ecfaa3ebd6fb 100644
--- a/extensions/crabbox/src/crabbox-worker-timeouts.ts
+++ b/extensions/crabbox/src/crabbox-worker-timeouts.ts
@@ -5,6 +5,8 @@ type CrabboxProvisionTimeoutProfile = {
 
 export const CRABBOX_WARMUP_TIMEOUT_MS = 240_000;
 export const CRABBOX_LIFECYCLE_TIMEOUT_MS = 60_000;
+// AWS coordinator heartbeat latency reached 107.6 seconds in production measurements.
+export const CRABBOX_HEARTBEAT_TIMEOUT_MS = 150_000;
 
 // `providers --json` is a static compiled report: no network, no credentials,
 // measured well under a second. The picker awaits it, so cap it far below the

From 14cebc477ada8cf5a31324039e5ba661f8f5da3e Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 14:14:26 -0700
Subject: [PATCH 096/124] fix(recovery): keep queued replies alive during
 session watchdog repair (#127510)

* fix(recovery): preserve queued turns during session watchdog repair

* test(plugins): make stalled response timeout deterministic
---
 ...diagnostic-session-recovery-coordinator.ts | 12 +--
 src/logging/diagnostic-session-recovery.ts    |  4 +-
 ...stuck-session-recovery.integration.test.ts | 68 ++++++++++++++
 ...tic-stuck-session-recovery.runtime.test.ts | 59 ++++++++++++
 ...agnostic-stuck-session-recovery.runtime.ts | 28 +++---
 src/logging/diagnostic.test.ts                | 94 ++++++++++---------
 test/scripts/plugins-assertions.test.ts       |  3 +
 7 files changed, 197 insertions(+), 71 deletions(-)

diff --git a/src/logging/diagnostic-session-recovery-coordinator.ts b/src/logging/diagnostic-session-recovery-coordinator.ts
index 6a830d851d8b..c4734156cce1 100644
--- a/src/logging/diagnostic-session-recovery-coordinator.ts
+++ b/src/logging/diagnostic-session-recovery-coordinator.ts
@@ -73,10 +73,6 @@ function emitSessionRecoveryCompleted(params: {
   });
 }
 
-function recoveryRequestKey(request: StuckSessionRecoveryRequest): string | undefined {
-  return resolveStuckSessionRecoveryRef(request);
-}
-
 function isRecoveryPromiseLike(
   value: void | StuckSessionRecoveryOutcome | Promise<void | StuckSessionRecoveryOutcome>,
 ): value is Promise<void | StuckSessionRecoveryOutcome> {
@@ -85,10 +81,6 @@ function isRecoveryPromiseLike(
   );
 }
 
-function recoveryOutcomeHasQueuedLaneWork(outcome: StuckSessionRecoveryOutcome): boolean {
-  return outcome.status === "aborted" && (outcome.queuedCount ?? 0) > 0;
-}
-
 function applyRecoveryOutcomeToDiagnosticState(params: {
   request: StuckSessionRecoveryRequest;
   outcome: StuckSessionRecoveryOutcome | undefined;
@@ -152,7 +144,7 @@ function applyRecoveryOutcomeToDiagnosticState(params: {
   state.lastStuckWarnAgeMs = undefined;
   state.lastLongRunningWarnAgeMs = undefined;
   const preserveQueuedIdleWork =
-    params.request.expectedState === "idle" && recoveryOutcomeHasQueuedLaneWork(params.outcome);
+    params.request.expectedState === "idle" && (params.outcome.queuedCount ?? 0) > 0;
   state.queueDepth = recoveryOutcomeClearsQueuedSessionState(params.outcome)
     ? 0
     : preserveQueuedIdleWork
@@ -174,7 +166,7 @@ function applyRecoveryOutcomeToDiagnosticState(params: {
 function requestStuckSessionRecoveryOutcome(
   params: RequestStuckSessionRecoveryParams,
 ): Promise<StuckSessionRecoveryOutcome | undefined> {
-  const inFlightKey = recoveryRequestKey(params.request);
+  const inFlightKey = resolveStuckSessionRecoveryRef(params.request);
   if (inFlightKey && recoveryRequestsInFlight.has(inFlightKey)) {
     const outcome: StuckSessionRecoveryOutcome = {
       status: "skipped",
diff --git a/src/logging/diagnostic-session-recovery.ts b/src/logging/diagnostic-session-recovery.ts
index b42343a51aa2..71061c195600 100644
--- a/src/logging/diagnostic-session-recovery.ts
+++ b/src/logging/diagnostic-session-recovery.ts
@@ -87,8 +87,8 @@ export function recoveryOutcomeClearsQueuedSessionState(
   outcome: StuckSessionRecoveryOutcome,
 ): boolean {
   return (
-    outcome.status === "released" ||
-    (outcome.status === "aborted" && outcome.released > 0 && (outcome.queuedCount ?? 0) === 0)
+    (outcome.status === "released" || (outcome.status === "aborted" && outcome.released > 0)) &&
+    (outcome.queuedCount ?? 0) === 0
   );
 }
 
diff --git a/src/logging/diagnostic-stuck-session-recovery.integration.test.ts b/src/logging/diagnostic-stuck-session-recovery.integration.test.ts
index e74c58b5bec0..8ff89b4bda69 100644
--- a/src/logging/diagnostic-stuck-session-recovery.integration.test.ts
+++ b/src/logging/diagnostic-stuck-session-recovery.integration.test.ts
@@ -139,6 +139,74 @@ describe("stuck session recovery integration", () => {
     unsubscribe();
   });
 
+  it.each(["preflight_compacting", "memory_flushing"] as const)(
+    "keeps real queued turns behind healthy %s work",
+    async (phase) => {
+      const sessionKey = `agent:main:healthy-${phase}`;
+      const sessionId = `healthy-${phase}-session`;
+      const lane = resolveEmbeddedSessionLane(sessionKey);
+      const operation = createReplyOperation({ sessionKey, sessionId, resetTriggered: false });
+      operation.setPhase(phase);
+      const handle = {
+        queueMessage: async () => {},
+        isStreaming: () => false,
+        isCompacting: () => phase === "preflight_compacting",
+        abort: () => {},
+      };
+      setActiveEmbeddedRun(sessionId, handle, sessionKey);
+
+      let releaseActive!: () => void;
+      let markActiveStarted!: () => void;
+      const activeStarted = new Promise<void>((resolve) => {
+        markActiveStarted = resolve;
+      });
+      const active = enqueueCommandInLane(
+        lane,
+        () =>
+          new Promise<void>((resolve) => {
+            releaseActive = resolve;
+            markActiveStarted();
+          }),
+        { warnAfterMs: Number.MAX_SAFE_INTEGER },
+      );
+      const queued = enqueueCommandInLane(lane, async () => "delivered", {
+        warnAfterMs: Number.MAX_SAFE_INTEGER,
+      });
+      await activeStarted;
+      operation.abortSignal.addEventListener(
+        "abort",
+        () => {
+          clearActiveEmbeddedRun(sessionId, handle, sessionKey);
+          operation.complete();
+          releaseActive();
+        },
+        { once: true },
+      );
+
+      try {
+        const outcome = await recoverStuckDiagnosticSession({
+          sessionId,
+          sessionKey,
+          ageMs: 720_000,
+          queueDepth: 1,
+          compactionSafetyTimeoutMs: 900_000,
+          allowActiveAbort: true,
+        });
+
+        expect(operation.abortSignal.aborted).toBe(false);
+        expect(outcome.status).toBe("skipped");
+        await expectPendingAfterEventLoopTurn(queued);
+        expect(getQueueSize(lane)).toBe(2);
+      } finally {
+        clearActiveEmbeddedRun(sessionId, handle, sessionKey);
+        operation.complete();
+        releaseActive();
+        await active;
+        await queued;
+      }
+    },
+  );
+
   it("does not reset a blocked lane while a reply operation is still active", async () => {
     const sessionKey = "agent:main:active-reply";
     const sessionId = "active-reply-session";
diff --git a/src/logging/diagnostic-stuck-session-recovery.runtime.test.ts b/src/logging/diagnostic-stuck-session-recovery.runtime.test.ts
index 5c36fe0284f8..4ac6804eac0d 100644
--- a/src/logging/diagnostic-stuck-session-recovery.runtime.test.ts
+++ b/src/logging/diagnostic-stuck-session-recovery.runtime.test.ts
@@ -520,6 +520,65 @@ describe("stuck session recovery", () => {
     },
   );
 
+  it.each(
+    (["preflight_compacting", "memory_flushing"] as const)
+      .flatMap((phase) =>
+        [false, true].flatMap((hasEmbeddedHandle) =>
+          [false, true].map((allowActiveAbort) => ({
+            phase,
+            hasEmbeddedHandle,
+            allowActiveAbort,
+            ageMs: 720_000,
+          })),
+        ),
+      )
+      .concat([
+        {
+          phase: "preflight_compacting",
+          hasEmbeddedHandle: false,
+          allowActiveAbort: false,
+          ageMs: 915_000,
+        },
+        {
+          phase: "memory_flushing",
+          hasEmbeddedHandle: true,
+          allowActiveAbort: true,
+          ageMs: 915_000,
+        },
+      ]),
+  )(
+    "honors the configured $phase timeout with queued work (handle=$hasEmbeddedHandle, abort=$allowActiveAbort, age=$ageMs)",
+    async ({ phase, hasEmbeddedHandle, allowActiveAbort, ageMs }) => {
+      const sessionId = "maintenance-reply-session";
+      mocks.resolveActiveEmbeddedRunSessionId.mockReturnValue(sessionId);
+      mocks.resolveActiveEmbeddedRunHandleSessionId.mockReturnValue(
+        hasEmbeddedHandle ? sessionId : undefined,
+      );
+      mocks.isEmbeddedAgentRunActive.mockReturnValue(true);
+      mocks.isEmbeddedAgentRunHandleActive.mockReturnValue(hasEmbeddedHandle);
+      mocks.resolveEmbeddedAgentReplyRunPhase.mockReturnValue(phase);
+      mocks.getDiagnosticSessionActivitySnapshot.mockReturnValue({ lastProgressAgeMs: ageMs });
+      mocks.abortEmbeddedAgentRun.mockReturnValue(true);
+      mocks.waitForEmbeddedAgentRunEnd.mockResolvedValue(true);
+
+      const outcome = await recoverStuckDiagnosticSession({
+        sessionId,
+        sessionKey: "agent:main:main",
+        ageMs,
+        queueDepth: 1,
+        allowActiveAbort,
+        staleActiveProgressAbortMs: 360_000,
+        compactionSafetyTimeoutMs: 900_000,
+      });
+
+      const withinCompactionSafetyWindow = ageMs < 915_000;
+      expect(outcome.status).toBe(withinCompactionSafetyWindow ? "skipped" : "aborted");
+      expect(mocks.abortEmbeddedAgentRun).toHaveBeenCalledTimes(
+        withinCompactionSafetyWindow ? 0 : 1,
+      );
+    },
+  );
+
   it("keeps reply-only ownership with recent progress even with zero queued backlog", async () => {
     mocks.resolveActiveEmbeddedRunSessionId.mockReturnValue("live-reply-session");
     mocks.resolveActiveEmbeddedRunHandleSessionId.mockReturnValue(undefined);
diff --git a/src/logging/diagnostic-stuck-session-recovery.runtime.ts b/src/logging/diagnostic-stuck-session-recovery.runtime.ts
index dc3f04e5ae71..8ae3db8e9865 100644
--- a/src/logging/diagnostic-stuck-session-recovery.runtime.ts
+++ b/src/logging/diagnostic-stuck-session-recovery.runtime.ts
@@ -180,14 +180,19 @@ export async function recoverStuckDiagnosticSession(
     const activeReplyPhase = activeWorkSessionId
       ? resolveEmbeddedAgentReplyRunPhase(activeWorkSessionId)
       : undefined;
+    const maintenancePhase =
+      activeReplyPhase === "preflight_compacting" || activeReplyPhase === "memory_flushing";
 
-    if (activeReplyPhase === "waiting_for_global_lane") {
-      // A global-lane queue owner is healthy pending work. Reclaiming it here
-      // reintroduces the silent reply drop that the wait phase prevents.
+    if (
+      activeReplyPhase === "waiting_for_global_lane" ||
+      (maintenancePhase && params.ageMs < staleActiveLaneTaskReleaseMs)
+    ) {
+      // Queued replies and configured maintenance own their lane until their
+      // producer finishes or the existing compaction safety window expires.
       return reportRecoveryOutcome({
         status: "skipped",
         action: "keep_lane",
-        reason: "global_lane_wait",
+        reason: maintenancePhase ? "active_reply_work" : "global_lane_wait",
         sessionId: params.sessionId,
         sessionKey: params.sessionKey,
         activeSessionId: activeWorkSessionId,
@@ -257,18 +262,9 @@ export async function recoverStuckDiagnosticSession(
           sessionKey: params.sessionKey,
           queueDepth: params.queueDepth,
           staleAbortMs: staleActiveProgressAbortMs,
-          // Reply-only ownership must expire when proven stale even with zero
-          // queued backlog; the queue gate exists to protect run handles that
-          // are actively draining queued turns, and there is no such backlog
-          // here to protect. Recognized maintenance phases are the exception:
-          // preflight compaction and memory flush are explicitly allowed to
-          // run longer than the stale threshold (they honor a configured
-          // compaction timeout), so they keep the queue-backlog guard and are
-          // never force-cleared early by this reclaim path.
-          requireQueueBacklog:
-            activeReplyPhase === "preflight_compacting" || activeReplyPhase === "memory_flushing"
-              ? undefined
-              : false,
+          // Maintenance retains its backlog gate after the safety window;
+          // other abandoned reply ownership must expire even without a queue.
+          requireQueueBacklog: maintenancePhase ? undefined : false,
         });
       if (params.allowActiveAbort === true || reclaimStaleReplyWork) {
         if (reclaimStaleReplyWork) {
diff --git a/src/logging/diagnostic.test.ts b/src/logging/diagnostic.test.ts
index b6b1b94e3d51..2c9d737a7308 100644
--- a/src/logging/diagnostic.test.ts
+++ b/src/logging/diagnostic.test.ts
@@ -1805,57 +1805,65 @@ describe("stuck session diagnostics threshold", () => {
     expect(s2Call!.allowActiveAbort).toBeUndefined();
   });
 
-  it("preserves queued idle work when abort reset releases active lane work", async () => {
-    const events: DiagnosticEventPayload[] = [];
-    const recoverStuckSession = vi.fn().mockResolvedValue({
+  it.each([
+    {
       status: "aborted",
       action: "abort_embedded_run",
-      sessionId: "s1",
-      sessionKey: "main",
-      activeSessionId: "s1",
-      activeWorkKind: "embedded_run",
       aborted: true,
       drained: false,
       forceCleared: true,
-      released: 1,
-      queuedCount: 1,
-    });
-    const unsubscribe = onDiagnosticEvent((event) => {
-      events.push(event);
-    });
-    try {
-      startDiagnosticHeartbeat(
-        {
-          diagnostics: {
-            enabled: true,
+    },
+    { status: "released", action: "release_lane", reason: "stale_lane_task" },
+  ] as const)(
+    "preserves queued idle work when $status recovery releases active lane work",
+    async (outcome) => {
+      const events: DiagnosticEventPayload[] = [];
+      const recoverStuckSession = vi.fn().mockResolvedValue({
+        sessionId: "s1",
+        sessionKey: "main",
+        activeSessionId: "s1",
+        activeWorkKind: "embedded_run",
+        released: 1,
+        queuedCount: 1,
+        ...outcome,
+      });
+      const unsubscribe = onDiagnosticEvent((event) => {
+        events.push(event);
+      });
+      try {
+        startDiagnosticHeartbeat(
+          {
+            diagnostics: {
+              enabled: true,
+            },
           },
+          { recoverStuckSession },
+        );
+        logSessionStateChange({ sessionId: "s1", sessionKey: "main", state: "processing" });
+        markDiagnosticEmbeddedRunStarted({ sessionId: "s1", sessionKey: "main" });
+        logSessionStateChange({ sessionId: "s1", sessionKey: "main", state: "idle" });
+
+        vi.advanceTimersByTime(59_000);
+        logMessageQueued({ sessionId: "s1", sessionKey: "main", source: "test-followup" });
+        vi.advanceTimersByTime(1_000);
+        await Promise.resolve();
+      } finally {
+        unsubscribe();
+      }
+
+      requireMatchingRecord(
+        events,
+        {
+          type: "session.state",
+          state: "idle",
+          reason: `stuck_recovery:${outcome.status}`,
+          queueDepth: 1,
         },
-        { recoverStuckSession },
+        `idle ${outcome.status} preserves queued work`,
       );
-      logSessionStateChange({ sessionId: "s1", sessionKey: "main", state: "processing" });
-      markDiagnosticEmbeddedRunStarted({ sessionId: "s1", sessionKey: "main" });
-      logSessionStateChange({ sessionId: "s1", sessionKey: "main", state: "idle" });
-
-      vi.advanceTimersByTime(59_000);
-      logMessageQueued({ sessionId: "s1", sessionKey: "main", source: "test-followup" });
-      vi.advanceTimersByTime(1_000);
-      await Promise.resolve();
-    } finally {
-      unsubscribe();
-    }
-
-    requireMatchingRecord(
-      events,
-      {
-        type: "session.state",
-        state: "idle",
-        reason: "stuck_recovery:aborted",
-        queueDepth: 1,
-      },
-      "idle abort preserves queued work",
-    );
-    expect(getDiagnosticSessionState({ sessionId: "s1", sessionKey: "main" }).queueDepth).toBe(1);
-  });
+      expect(getDiagnosticSessionState({ sessionId: "s1", sessionKey: "main" }).queueDepth).toBe(1);
+    },
+  );
 
   it("marks diagnostic session state idle only after a mutating recovery outcome", async () => {
     const events: DiagnosticEventPayload[] = [];
diff --git a/test/scripts/plugins-assertions.test.ts b/test/scripts/plugins-assertions.test.ts
index 62372d9c0c03..aee5ad71c308 100644
--- a/test/scripts/plugins-assertions.test.ts
+++ b/test/scripts/plugins-assertions.test.ts
@@ -1631,6 +1631,9 @@ ${command}
       const result = await runAssertionAsync(["clawhub-preflight"], {
         CLAWHUB_PLUGIN_ID: "openclaw-kitchen-sink-fixture",
         CLAWHUB_PLUGIN_SPEC: "clawhub:@openclaw/kitchen-sink",
+        NODE_OPTIONS: `--import=data:text/javascript,${encodeURIComponent(
+          "const response = await fetch(process.env.OPENCLAW_CLAWHUB_URL); globalThis.fetch = async () => response;",
+        )}`,
         OPENCLAW_CLAWHUB_URL: `http://127.0.0.1:${address.port}`,
         OPENCLAW_PLUGINS_E2E_CLAWHUB_PREFLIGHT_TIMEOUT_MS: "75",
       });

From b6894751d24bd240880d7254c784d3f78f06a7c6 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 14:16:38 -0700
Subject: [PATCH 097/124] test(msteams): pin reply threading and reaction
 routing across conversation kinds (#127568)

Table-driven regressions prove personal and group sends never carry a
Teams thread suffix while channels preserve ;messageid, and that agent
react actions route to the prepared Graph target per conversation kind
with exact result payloads and inbound reaction event labels.

Parity proof for Microsoft Lobster patches 0038/0026 via
giodl73-repo/lobster-plugins-and-patches.
---
 .../msteams/src/channel.actions.test.ts       | 160 ++++++------------
 .../message-handler.thread-parent.test.ts     |  26 ++-
 .../monitor-handler/reaction-handler.test.ts  |  55 +++---
 extensions/msteams/src/send-context.test.ts   |  74 +++++++-
 4 files changed, 177 insertions(+), 138 deletions(-)

diff --git a/extensions/msteams/src/channel.actions.test.ts b/extensions/msteams/src/channel.actions.test.ts
index 94f8fe688c12..de835c6f3ddc 100644
--- a/extensions/msteams/src/channel.actions.test.ts
+++ b/extensions/msteams/src/channel.actions.test.ts
@@ -81,7 +81,6 @@ const currentChannelId = "conversation:19:ctx@thread.tacv2";
 const graphTeamId = "11111111-1111-1111-1111-111111111111";
 const graphChannelId = "19:channel-1@thread.tacv2";
 const graphChannelTarget = `${graphTeamId}/${graphChannelId}`;
-const reactChannelId = "conversation:19:react@thread.tacv2";
 const targetChannelId = "conversation:19:target@thread.tacv2";
 const editedConversationId = "19:edited@thread.tacv2";
 const editedMessageId = "msg-edit-1";
@@ -1056,37 +1055,61 @@ describe("msteamsPlugin message actions", () => {
     expect(properties).toHaveProperty("pinnedMessageId");
   });
 
-  it("reuses currentChannelId fallback for react actions", async () => {
-    await expectSuccessfulAction({
-      mockFn: reactMessageMSTeamsMock,
-      mockResult: { ok: true },
-      action: "react",
-      cfg: unrestrictedReadCfg,
-      accountId: "default",
-      requesterAccountId: "default",
-      actionParams: {
-        messageId: padded("msg-3"),
-        emoji: padded(reactionType),
-      },
-      toolContext: {
-        currentChannelId: padded(reactChannelId),
-      },
-      runtimeParams: {
-        to: reactChannelId,
-        messageId: "msg-3",
-        reactionType,
-      },
-      details: okMSTeamsActionDetails("react", {
-        reactionType,
-      }),
-      contentDetails: {
-        channel: "msteams",
+  it.each([
+    {
+      chatType: "channel",
+      conversationTarget: "conversation:19:c@thread.tacv2",
+      currentMessagingTarget: "team-1/19:c@thread.tacv2",
+      expectedTarget: "team-1/19:c@thread.tacv2",
+    },
+    {
+      chatType: "group",
+      conversationTarget: "conversation:19:g@thread.v2",
+      currentMessagingTarget: undefined,
+      expectedTarget: "conversation:19:g@thread.v2",
+    },
+    {
+      chatType: "direct",
+      conversationTarget: "conversation:a:dm",
+      currentMessagingTarget: undefined,
+      expectedTarget: "conversation:a:dm",
+    },
+  ] as const)(
+    "routes agent react actions and preserves their result shape for $chatType turns",
+    async ({ chatType, conversationTarget, currentMessagingTarget, expectedTarget }) => {
+      await expectSuccessfulAction({
+        mockFn: reactMessageMSTeamsMock,
+        mockResult: { ok: true },
         action: "react",
-        reactionType,
-        ok: true,
-      },
-    });
-  });
+        cfg: unrestrictedReadCfg,
+        accountId: "default",
+        requesterAccountId: "default",
+        actionParams: {
+          ...(chatType === "channel" ? { target: conversationTarget } : {}),
+          messageId: padded("msg-react"),
+          emoji: padded(reactionType),
+        },
+        toolContext: {
+          currentChannelProvider: "msteams",
+          currentChannelId: padded(conversationTarget),
+          currentChatType: chatType,
+          ...(currentMessagingTarget ? { currentMessagingTarget } : {}),
+        },
+        runtimeParams: {
+          to: expectedTarget,
+          messageId: "msg-react",
+          reactionType,
+        },
+        details: okMSTeamsActionDetails("react", { reactionType }),
+        contentDetails: {
+          channel: "msteams",
+          action: "react",
+          reactionType,
+          ok: true,
+        },
+      });
+    },
+  );
 
   it("shares the missing target and messageId validation across actions", async () => {
     await expectActionParamError("delete", {}, deleteMissingTargetError);
@@ -1309,46 +1332,6 @@ describe("msteamsPlugin message actions", () => {
     expect(testCase.runtimeMock).not.toHaveBeenCalled();
   });
 
-  it("restores the Graph route from a core-materialized channel target", async () => {
-    // Core materializes an omitted target from currentChannelId before plugin
-    // dispatch. Teams must restore the prepared Graph target for channel turns.
-    const teamChannelTarget = "team-1/19:channel-abc@thread.tacv2";
-    const conversationTarget = "conversation:19:channel-abc@thread.tacv2";
-    await expectSuccessfulAction({
-      mockFn: reactMessageMSTeamsMock,
-      mockResult: { ok: true },
-      action: "react",
-      cfg: unrestrictedReadCfg,
-      accountId: "default",
-      requesterAccountId: "default",
-      actionParams: {
-        target: conversationTarget,
-        messageId: "msg-channel-react",
-        emoji: reactionType,
-      },
-      toolContext: {
-        currentChannelProvider: "msteams",
-        currentChannelId: conversationTarget,
-        currentChatType: "channel",
-        currentMessagingTarget: teamChannelTarget,
-      },
-      runtimeParams: {
-        to: teamChannelTarget,
-        messageId: "msg-channel-react",
-        reactionType,
-      },
-      details: okMSTeamsActionDetails("react", {
-        reactionType,
-      }),
-      contentDetails: {
-        channel: "msteams",
-        action: "react",
-        reactionType,
-        ok: true,
-      },
-    });
-  });
-
   it("preserves explicit teamId/channelId target over toolContext fallback", async () => {
     // Even in a channel context with a compound currentChannelId, an
     // explicit `target` param must take precedence.
@@ -1384,41 +1367,6 @@ describe("msteamsPlugin message actions", () => {
       },
     });
   });
-
-  it("keeps chat conversation fallback targets as-is for DM react actions", async () => {
-    // DM/group-chat turns continue to set currentChannelId to a
-    // `conversation:<id>` string (no `teamId/` prefix), which the runtime
-    // will resolve through `/chats/{id}`.
-    const dmFallback = "conversation:19:chat-dm@thread.skype";
-    await expectSuccessfulAction({
-      mockFn: reactMessageMSTeamsMock,
-      mockResult: { ok: true },
-      action: "react",
-      cfg: unrestrictedReadCfg,
-      actionParams: {
-        messageId: "msg-dm-react",
-        emoji: reactionType,
-      },
-      toolContext: {
-        currentChannelId: dmFallback,
-        currentChatType: "direct",
-      },
-      runtimeParams: {
-        to: dmFallback,
-        messageId: "msg-dm-react",
-        reactionType,
-      },
-      details: okMSTeamsActionDetails("react", {
-        reactionType,
-      }),
-      contentDetails: {
-        channel: "msteams",
-        action: "react",
-        reactionType,
-        ok: true,
-      },
-    });
-  });
 });
 
 describe("msteamsPlugin.threading.buildToolContext", () => {
diff --git a/extensions/msteams/src/monitor-handler/message-handler.thread-parent.test.ts b/extensions/msteams/src/monitor-handler/message-handler.thread-parent.test.ts
index c85a30cf44f7..aad939abe5c4 100644
--- a/extensions/msteams/src/monitor-handler/message-handler.thread-parent.test.ts
+++ b/extensions/msteams/src/monitor-handler/message-handler.thread-parent.test.ts
@@ -224,14 +224,14 @@ describe("msteams thread parent context injection", () => {
     expect(runtimeApiMockState.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledTimes(1);
   });
 
-  it("does not fetch parent for DM replyToId", async () => {
+  it("keeps inbound DM reply targets flat under threaded reply configuration", async () => {
     fetchChannelMessageMock.mockResolvedValue({
       id: "x",
       from: { user: { displayName: "Alice" } },
       body: { content: "should-not-happen", contentType: "text" },
     });
-    const { deps, enqueueSystemEvent } = createMessageHandlerDeps({
-      channels: { msteams: { allowFrom: ["*"] } },
+    const { conversationStore, deps, enqueueSystemEvent } = createMessageHandlerDeps({
+      channels: { msteams: { allowFrom: ["*"], replyStyle: "thread" } },
     } as OpenClawConfig);
     const handler = createMSTeamsMessageHandler(deps);
 
@@ -248,6 +248,26 @@ describe("msteams thread parent context injection", () => {
 
     expect(fetchChannelMessageMock).not.toHaveBeenCalled();
     expect(findParentSystemEventCall(enqueueSystemEvent)).toBeUndefined();
+    expect(conversationStore.upsert).toHaveBeenCalledWith(
+      "a:dm-conversation",
+      expect.objectContaining({
+        conversation: expect.objectContaining({
+          id: "a:dm-conversation",
+          conversationType: "personal",
+        }),
+      }),
+    );
+    expect(conversationStore.upsert).not.toHaveBeenCalledWith(
+      "a:dm-conversation",
+      expect.objectContaining({ threadId: expect.any(String) }),
+    );
+    const dispatchContext =
+      runtimeApiMockState.dispatchReplyWithBufferedBlockDispatcher.mock.calls[0]?.[0].ctx;
+    expect(dispatchContext).toMatchObject({
+      To: "user:user-aad",
+      OriginatingTo: "conversation:a:dm-conversation",
+    });
+    expect(dispatchContext?.MessageThreadId).toBeUndefined();
   });
 
   it("does not fetch parent for top-level channel messages without replyToId", async () => {
diff --git a/extensions/msteams/src/monitor-handler/reaction-handler.test.ts b/extensions/msteams/src/monitor-handler/reaction-handler.test.ts
index 7464a14527b0..d9c37ebe6224 100644
--- a/extensions/msteams/src/monitor-handler/reaction-handler.test.ts
+++ b/extensions/msteams/src/monitor-handler/reaction-handler.test.ts
@@ -57,7 +57,7 @@ function createReactionTestHarness() {
   setMSTeamsRuntime(mockRuntime);
 
   const cfg: OpenClawConfig = {
-    channels: { msteams: { allowFrom: ["allowed-aad"] } },
+    channels: { msteams: { allowFrom: ["allowed-aad"], groupPolicy: "open" } },
   } as OpenClawConfig;
 
   const deps = buildDeps(cfg, mockRuntime);
@@ -83,14 +83,6 @@ function firstEnqueueLabel(enqueue: ReturnType<typeof vi.fn>): string {
   return label;
 }
 
-function firstEnqueueMeta(enqueue: ReturnType<typeof vi.fn>): Record<string, unknown> {
-  const [, meta] = firstEnqueueCall(enqueue);
-  if (!meta || typeof meta !== "object") {
-    throw new Error("Expected enqueueSystemEvent metadata");
-  }
-  return meta as Record<string, unknown>;
-}
-
 async function invokeReactionEvent(
   handler: ReturnType<typeof createMSTeamsReactionHandler>,
   activity: Record<string, unknown>,
@@ -190,25 +182,34 @@ describe("createMSTeamsReactionHandler", () => {
   });
 
   describe("inbound reaction events", () => {
-    it("enqueues system event for reactionsAdded", async () => {
-      const { handler, enqueue } = createReactionTestHarness();
-      await invokeReactionEvent(
-        handler,
-        {
-          reactionsAdded: [{ type: "like" }],
-          from: { id: "u1", aadObjectId: "allowed-aad", name: "User" },
-          replyToId: "msg-1",
-        },
-        "added",
-      );
+    it.each([
+      { conversationType: "personal", conversationId: "a:dm" },
+      { conversationType: "groupChat", conversationId: "19:g@thread.v2" },
+      { conversationType: "channel", conversationId: "19:c@thread.tacv2" },
+    ] as const)(
+      "enqueues the exact inbound reaction event label for $conversationType conversations",
+      async ({ conversationType, conversationId }) => {
+        const { handler, enqueue } = createReactionTestHarness();
+        await invokeReactionEvent(
+          handler,
+          {
+            reactionsAdded: [{ type: "like" }],
+            from: { id: "u1", aadObjectId: "allowed-aad", name: "User" },
+            conversation: { id: conversationId, conversationType },
+            replyToId: "msg-1",
+          },
+          "added",
+        );
 
-      expect(enqueue).toHaveBeenCalledOnce();
-      const label = firstEnqueueLabel(enqueue);
-      const meta = firstEnqueueMeta(enqueue);
-      expect(label).toContain("added");
-      expect(meta.sessionKey).toBe("test-session");
-      expect(meta.contextKey).toContain("added");
-    });
+        expect(enqueue).toHaveBeenCalledExactlyOnceWith(
+          "Teams reaction 👍 added by User on message msg-1",
+          {
+            sessionKey: "test-session",
+            contextKey: `msteams:reaction:${conversationId}:msg-1:allowed-aad:like:added`,
+          },
+        );
+      },
+    );
 
     it("enqueues system event for reactionsRemoved", async () => {
       const { handler, enqueue } = createReactionTestHarness();
diff --git a/extensions/msteams/src/send-context.test.ts b/extensions/msteams/src/send-context.test.ts
index 512dc6ac74ce..f41fdbc92362 100644
--- a/extensions/msteams/src/send-context.test.ts
+++ b/extensions/msteams/src/send-context.test.ts
@@ -3,9 +3,12 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { MSTeamsConfig, OpenClawConfig } from "../runtime-api.js";
 import type { StoredConversationReference } from "./conversation-store.js";
 import { resolveMSTeamsSendContext } from "./send-context.js";
+import { sendMessageMSTeams } from "./send.js";
 
 const sendContextMockState = vi.hoisted(() => {
   const getAccessToken = vi.fn();
+  const createActivity = vi.fn(async () => ({ id: "message-1" }));
+  const getActivities = vi.fn(() => ({ create: createActivity }));
   const store = {
     upsert: vi.fn(),
     get: vi.fn(),
@@ -15,9 +18,20 @@ const sendContextMockState = vi.hoisted(() => {
   };
   return {
     store,
-    loadMSTeamsSdkWithAuth: vi.fn(async () => ({ app: { id: "mock-app" } })),
+    loadMSTeamsSdkWithAuth: vi.fn(async () => ({
+      app: {
+        id: "mock-app",
+        api: {
+          serviceUrl: "https://smba.trafficmanager.net/amer/",
+          conversations: { activities: getActivities },
+        },
+      },
+    })),
     createMSTeamsTokenProvider: vi.fn(() => ({ getAccessToken })),
+    createActivity,
+    getActivities,
     getAccessToken,
+    logInfo: vi.fn(),
     logWarn: vi.fn(),
   };
 });
@@ -29,7 +43,10 @@ vi.mock("./conversation-store-state.js", () => ({
 vi.mock("./runtime.js", () => ({
   getMSTeamsRuntime: () => ({
     logging: {
-      getChildLogger: () => ({ warn: sendContextMockState.logWarn }),
+      getChildLogger: () => ({
+        info: sendContextMockState.logInfo,
+        warn: sendContextMockState.logWarn,
+      }),
     },
   }),
 }));
@@ -94,7 +111,10 @@ beforeEach(() => {
   sendContextMockState.store.findPreferredDmByUserId.mockReset();
   sendContextMockState.loadMSTeamsSdkWithAuth.mockClear();
   sendContextMockState.createMSTeamsTokenProvider.mockClear();
+  sendContextMockState.createActivity.mockClear();
+  sendContextMockState.getActivities.mockClear();
   sendContextMockState.getAccessToken.mockReset();
+  sendContextMockState.logInfo.mockReset();
   sendContextMockState.logWarn.mockReset();
   vi.unstubAllEnvs();
 });
@@ -162,6 +182,56 @@ describe("resolveMSTeamsSendContext", () => {
     expect(sendContextMockState.store.get).toHaveBeenCalledWith("19:channel@thread.tacv2");
   });
 
+  it.each([
+    { conversationType: "personal", conversationId: "a:dm", expectedSuffix: "" },
+    { conversationType: "groupChat", conversationId: "19:g@thread.v2", expectedSuffix: "" },
+    {
+      conversationType: "channel",
+      conversationId: "19:c@thread.tacv2",
+      expectedSuffix: ";messageid=root-1",
+    },
+  ] as const)(
+    "sends explicit threaded $conversationType targets to the correct SDK conversation",
+    async ({ conversationType, conversationId, expectedSuffix }) => {
+      sendContextMockState.store.get.mockResolvedValue(
+        channelRef({
+          serviceUrl: "https://smba.trafficmanager.net/amer/",
+          threadId: "root-1",
+          conversation: { id: conversationId, conversationType },
+        }),
+      );
+
+      await sendMessageMSTeams({
+        cfg: {
+          channels: {
+            msteams: {
+              enabled: true,
+              appId: "app-id",
+              appPassword: "app-password",
+              tenantId: "tenant-id",
+              replyStyle: "thread",
+            },
+          },
+        } as OpenClawConfig,
+        to: `conversation:${conversationId};messageid=root-1`,
+        text: "parity proof",
+      });
+
+      expect(sendContextMockState.store.get).toHaveBeenCalledWith(conversationId);
+      expect(sendContextMockState.getActivities).toHaveBeenCalledExactlyOnceWith(
+        `${conversationId}${expectedSuffix}`,
+      );
+      expect(sendContextMockState.createActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          conversation: expect.objectContaining({
+            id: `${conversationId}${expectedSuffix}`,
+            conversationType,
+          }),
+        }),
+      );
+    },
+  );
+
   it("resolves Graph team/channel targets through the stored channel conversation", async () => {
     sendContextMockState.store.get.mockResolvedValue(
       channelRef({

From 69d30923bfd9c3027c6dac5ca2291242549dd19b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 14:17:24 -0700
Subject: [PATCH 098/124] perf(test): speed up model provider recovery
 observations (#127570)

---
 .../model-providers-page.test.ts              | 22 +++++++++----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/ui/src/pages/model-providers/model-providers-page.test.ts b/ui/src/pages/model-providers/model-providers-page.test.ts
index 958be433ed7f..04280d8f6fce 100644
--- a/ui/src/pages/model-providers/model-providers-page.test.ts
+++ b/ui/src/pages/model-providers/model-providers-page.test.ts
@@ -250,7 +250,7 @@ describe("ModelProvidersPage agent scope", () => {
         page.routeData = routeData;
       }
       document.body.append(page);
-      await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: false }));
+      await waitForFast(() => expect(page.data?.providerUsage).toMatchObject({ ok: false }));
       const previousCalls = requestCount(request, "usage.status");
       providerUnavailable = false;
 
@@ -259,7 +259,7 @@ describe("ModelProvidersPage agent scope", () => {
       await vi.waitFor(() => {
         expect(requestCount(request, "usage.status")).toBe(previousCalls + 1);
       });
-      await vi.waitFor(() =>
+      await waitForFast(() =>
         expect(page.data?.providerUsage).toEqual({
           ok: true,
           value: { updatedAt: 1, providers: [] },
@@ -293,7 +293,7 @@ describe("ModelProvidersPage agent scope", () => {
         };
       }
       document.body.append(page);
-      await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
+      await waitForFast(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
       const previousCalls = requestCount(request, "usage.status");
 
       window.dispatchEvent(new Event("focus"));
@@ -321,14 +321,14 @@ describe("ModelProvidersPage agent scope", () => {
       return originalRequest(method);
     });
     const page = appendPage(context);
-    await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: false }));
+    await waitForFast(() => expect(page.data?.providerUsage).toMatchObject({ ok: false }));
     providerUnavailable = false;
 
     source.publish({ ...snapshot, phase: "reconnecting" });
     source.publish({ ...snapshot, phase: "connected" });
 
     await vi.waitFor(() => expect(requestCount(request, "usage.status")).toBe(2));
-    await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
+    await waitForFast(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
   });
 
   it("defers failed provider usage recovery while hidden until page activation", async () => {
@@ -346,7 +346,7 @@ describe("ModelProvidersPage agent scope", () => {
       return originalRequest(method);
     });
     const page = appendPage(context);
-    await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: false }));
+    await waitForFast(() => expect(page.data?.providerUsage).toMatchObject({ ok: false }));
     providerUnavailable = false;
 
     source.publish({ ...snapshot, phase: "reconnecting" });
@@ -357,7 +357,7 @@ describe("ModelProvidersPage agent scope", () => {
     document.dispatchEvent(new Event("visibilitychange"));
 
     await vi.waitFor(() => expect(requestCount(request, "usage.status")).toBe(2));
-    await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
+    await waitForFast(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
   });
 
   it("supersedes a hung load on disconnect so reconnect can replace it", async () => {
@@ -367,7 +367,7 @@ describe("ModelProvidersPage agent scope", () => {
     vi.spyOn(document, "hasFocus").mockReturnValue(true);
     vi.spyOn(document, "visibilityState", "get").mockReturnValue("visible");
     const page = appendPage(context);
-    await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
+    await waitForFast(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
     deferNextAuthStatus();
     void page.refresh({ force: true });
     await vi.waitFor(() => expect(requestCount(request, "models.authStatus")).toBe(2));
@@ -376,7 +376,7 @@ describe("ModelProvidersPage agent scope", () => {
     source.publish({ ...snapshot, phase: "connected" });
 
     await vi.waitFor(() => expect(requestCount(request, "models.authStatus")).toBe(3));
-    await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
+    await waitForFast(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
   });
 
   it("keeps direct data visible while a same-client reconnect replaces it", async () => {
@@ -386,7 +386,7 @@ describe("ModelProvidersPage agent scope", () => {
     vi.spyOn(document, "hasFocus").mockReturnValue(true);
     vi.spyOn(document, "visibilityState", "get").mockReturnValue("visible");
     const page = appendPage(context);
-    await vi.waitFor(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
+    await waitForFast(() => expect(page.data?.providerUsage).toMatchObject({ ok: true }));
     const previousData = page.data;
     const originalRequest = request.getMockImplementation()!;
     request.mockImplementation(async (method: string) => {
@@ -406,7 +406,7 @@ describe("ModelProvidersPage agent scope", () => {
     expect(page.data).toBe(previousData);
 
     release();
-    await vi.waitFor(() =>
+    await waitForFast(() =>
       expect(page.data?.config).toEqual({
         agents: { defaults: { model: "openai/replacement-model" } },
       }),

From 41acededbc5751d6c6eafa0716c73326459451b4 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 14:21:07 -0700
Subject: [PATCH 099/124] perf(gateway-client): skip unused timing dispatch
 (#127566)

Co-authored-by: Amp <amp@ampcode.com>
---
 .../gateway-client/src/pending-request.ts     |  30 ++--
 .../src/protocol-client.request.test.ts       | 154 +++++++++++++++++-
 2 files changed, 166 insertions(+), 18 deletions(-)

diff --git a/packages/gateway-client/src/pending-request.ts b/packages/gateway-client/src/pending-request.ts
index 83558ff79a6e..50b417fad775 100644
--- a/packages/gateway-client/src/pending-request.ts
+++ b/packages/gateway-client/src/pending-request.ts
@@ -212,17 +212,25 @@ export class GatewayPendingRequests {
     errorCode?: string,
   ): void {
     const endedAtMs = this.opts.nowMs();
-    this.invoke("request timing", () =>
-      this.opts.onTiming?.({
-        id,
-        method: pending.method,
-        ok,
-        durationMs: Math.max(0, endedAtMs - pending.startedAtMs),
-        startedAtMs: pending.startedAtMs,
-        endedAtMs,
-        errorCode,
-      }),
-    );
+    try {
+      const onTiming = this.opts.onTiming;
+      if (onTiming === undefined || onTiming === null) {
+        return;
+      }
+      Reflect.apply(onTiming, this.opts, [
+        {
+          id,
+          method: pending.method,
+          ok,
+          durationMs: Math.max(0, endedAtMs - pending.startedAtMs),
+          startedAtMs: pending.startedAtMs,
+          endedAtMs,
+          errorCode,
+        },
+      ]);
+    } catch (error) {
+      this.opts.onCallbackError?.("request timing", error);
+    }
   }
 
   private invoke(label: string, callback: () => void): void {
diff --git a/packages/gateway-client/src/protocol-client.request.test.ts b/packages/gateway-client/src/protocol-client.request.test.ts
index 60b101bc8612..b25e35ec1316 100644
--- a/packages/gateway-client/src/protocol-client.request.test.ts
+++ b/packages/gateway-client/src/protocol-client.request.test.ts
@@ -23,7 +23,7 @@ type RequestConnection = {
 function createRequestHarness(options?: {
   createRequestId?: () => string;
   requestTimeoutMs?: number;
-  onRequestTiming?: (timing: GatewayProtocolRequestTiming) => void;
+  onRequestTiming?: (this: unknown, timing: GatewayProtocolRequestTiming) => void;
   onCallbackError?: (label: string, error: unknown) => void;
   send?: (frame: RequestFrame) => void;
   nowMs?: () => number;
@@ -279,8 +279,33 @@ describe("GatewayProtocolClient requests", () => {
 
   it("isolates callbacks while preserving accepted/final settlement and timing", async () => {
     let nowMs = 10;
-    const onRequestTiming = vi.fn<(timing: GatewayProtocolRequestTiming) => void>();
-    const onCallbackError = vi.fn<(label: string, error: unknown) => void>();
+    const trace: string[] = [];
+    const sentError = new Error("sent callback failed");
+    const acceptedError = new Error("accepted callback failed");
+    const timingError = new Error("timing callback failed");
+    const timingReceivers: unknown[] = [];
+    let timing: GatewayProtocolRequestTiming | undefined;
+    let callPropertyReads = 0;
+    const onRequestTiming = new Proxy(
+      function (this: unknown, value: GatewayProtocolRequestTiming) {
+        trace.push("timing");
+        timingReceivers.push(this);
+        timing = value;
+        throw timingError;
+      },
+      {
+        get(target, property, receiver) {
+          if (property === "call") {
+            callPropertyReads += 1;
+            throw new Error("timing callback .call must not be read");
+          }
+          return Reflect.get(target, property, receiver);
+        },
+      },
+    );
+    const onCallbackError = vi.fn<(label: string, error: unknown) => void>((label) => {
+      trace.push(`error:${label}`);
+    });
     const { client, connections } = createRequestHarness({
       nowMs: () => nowMs,
       onRequestTiming,
@@ -297,10 +322,12 @@ describe("GatewayProtocolClient requests", () => {
         timeoutMs: null,
         expectFinal: true,
         onSent: () => {
-          throw new Error("sent callback failed");
+          trace.push("sent");
+          throw sentError;
         },
         onAccepted: () => {
-          throw new Error("accepted callback failed");
+          trace.push("accepted");
+          throw acceptedError;
         },
       },
     );
@@ -311,8 +338,25 @@ describe("GatewayProtocolClient requests", () => {
     respond(connection, frame.id, { status: "ok" });
 
     await expect(request).resolves.toEqual({ status: "ok" });
-    expect(onCallbackError.mock.calls.map(([label]) => label)).toEqual(["sent", "accepted"]);
-    expect(onRequestTiming).toHaveBeenCalledExactlyOnceWith({
+    trace.push("resolved");
+    expect(trace).toEqual([
+      "sent",
+      "error:sent",
+      "accepted",
+      "error:accepted",
+      "timing",
+      "error:request timing",
+      "resolved",
+    ]);
+    expect(onCallbackError.mock.calls).toEqual([
+      ["sent", sentError],
+      ["accepted", acceptedError],
+      ["request timing", timingError],
+    ]);
+    expect(callPropertyReads).toBe(0);
+    expect(timingReceivers).toHaveLength(1);
+    expect(timingReceivers[0]).toMatchObject({ onTiming: onRequestTiming });
+    expect(timing).toEqual({
       id: frame.id,
       method: "agent",
       ok: true,
@@ -323,6 +367,102 @@ describe("GatewayProtocolClient requests", () => {
     client.stop();
   });
 
+  it("isolates a timing accessor installed through the callback receiver", async () => {
+    const timingAccessorError = new Error("timing accessor failed");
+    const trace: string[] = [];
+    const timingReceivers: unknown[] = [];
+    const onRequestTiming = function (this: unknown, timing: GatewayProtocolRequestTiming) {
+      trace.push(`timing:${timing.method}`);
+      timingReceivers.push(this);
+    };
+    const onCallbackError = vi.fn<(label: string, error: unknown) => void>((label) => {
+      trace.push(`error:${label}`);
+    });
+    const { client, connections } = createRequestHarness({ onRequestTiming, onCallbackError });
+    const connection = connections[0];
+    if (!connection) {
+      throw new Error("expected request connection");
+    }
+
+    const first = client.request("first", {}, { timeoutMs: null });
+    respond(connection, latestFrame(connection).id, { first: true });
+    await expect(first).resolves.toEqual({ first: true });
+    trace.push("resolved:first");
+    const timingReceiver = timingReceivers[0];
+    if (!timingReceiver || typeof timingReceiver !== "object") {
+      throw new Error("expected timing callback receiver");
+    }
+    Object.defineProperty(timingReceiver, "onTiming", {
+      configurable: true,
+      get: () => {
+        trace.push("get:onTiming");
+        throw timingAccessorError;
+      },
+    });
+
+    const second = client.request("second", {}, { timeoutMs: null });
+    respond(connection, latestFrame(connection).id, { second: true });
+    await expect(second).resolves.toEqual({ second: true });
+    trace.push("resolved:second");
+
+    expect(trace).toEqual([
+      "timing:first",
+      "resolved:first",
+      "get:onTiming",
+      "error:request timing",
+      "resolved:second",
+    ]);
+    expect(onCallbackError).toHaveBeenCalledExactlyOnceWith("request timing", timingAccessorError);
+    expect(client.hasPendingRequests).toBe(false);
+    client.stop();
+  });
+
+  it("isolates a falsy timing callback installed through the callback receiver", async () => {
+    const trace: string[] = [];
+    const callbackErrors: unknown[] = [];
+    const onRequestTiming = function (this: unknown, timing: GatewayProtocolRequestTiming) {
+      trace.push(`timing:${timing.method}`);
+      if (!this || typeof this !== "object") {
+        throw new Error("expected timing callback receiver");
+      }
+      Object.defineProperty(this, "onTiming", { configurable: true, value: false });
+    };
+    const onCallbackError = vi.fn<(label: string, error: unknown) => void>((label, error) => {
+      trace.push(`error:${label}`);
+      callbackErrors.push(error);
+    });
+    const { client, connections } = createRequestHarness({ onRequestTiming, onCallbackError });
+    const connection = connections[0];
+    if (!connection) {
+      throw new Error("expected request connection");
+    }
+
+    const firstPayload = { first: true };
+    const first = client.request("first", {}, { timeoutMs: null });
+    respond(connection, latestFrame(connection).id, firstPayload);
+    await expect(first).resolves.toEqual(firstPayload);
+    trace.push("resolved:first");
+
+    const secondPayload = { second: true };
+    const second = client.request("second", {}, { timeoutMs: null });
+    respond(connection, latestFrame(connection).id, secondPayload);
+    await expect(second).resolves.toEqual(secondPayload);
+    trace.push("resolved:second");
+
+    expect(trace).toEqual([
+      "timing:first",
+      "resolved:first",
+      "error:request timing",
+      "resolved:second",
+    ]);
+    expect(callbackErrors).toHaveLength(1);
+    const callbackError = callbackErrors[0];
+    expect(callbackError).toBeInstanceOf(TypeError);
+    expect(onCallbackError).toHaveBeenCalledExactlyOnceWith("request timing", callbackError);
+    expect(client.hasPendingRequests).toBe(false);
+    client.stop();
+  });
+
   it("clears generation tombstones when the socket flushes", async () => {
     vi.useFakeTimers();
     const { client, connections } = createRequestHarness({ createRequestId: () => "same-id" });

From c18654bf01a3bc246318960bdfaf86d2ab3c79a2 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 14:31:26 -0700
Subject: [PATCH 100/124] fix(agents): preserve approved exec output stream
 labels (#127595)

Adopted from Microsoft's Lobster patch 0013 via
giodl73-repo/lobster-plugins-and-patches (source commit e9f84234ebdf).
---
 .../bash-tools.exec-approval-output.test.ts   | 46 +++++++++++++++++++
 src/agents/bash-tools.exec-approval-output.ts | 12 ++++-
 2 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/src/agents/bash-tools.exec-approval-output.test.ts b/src/agents/bash-tools.exec-approval-output.test.ts
index cb58fb18083e..a72dde66c960 100644
--- a/src/agents/bash-tools.exec-approval-output.test.ts
+++ b/src/agents/bash-tools.exec-approval-output.test.ts
@@ -74,6 +74,33 @@ describe("formatExecApprovalContinuationSourceOutput", () => {
     expect(formatted.endsWith("b")).toBe(true);
   });
 
+  it.each([
+    { name: "stderr", label: "stderr", stdoutUnits: 200_000, streamUnits: 100_000 },
+    { name: "error", label: "error", stdoutUnits: 200_000, streamUnits: 100_000 },
+    { name: "head header cut", label: "stderr", stdoutUnits: 191_907, streamUnits: 100_000 },
+    { name: "tail header cut", label: "stderr", stdoutUnits: 200_000, streamUnits: 63_970 },
+    { name: "already retained header", label: "stderr", stdoutUnits: 200_000, streamUnits: 63_960 },
+  ])("preserves the retained stream label across $name", ({ label, stdoutUnits, streamUnits }) => {
+    const formatted = formatExecApprovalContinuationSourceOutput([
+      { label: "stdout", value: "a".repeat(stdoutUnits) },
+      { label, value: "b".repeat(streamUnits) },
+    ]);
+
+    expect(formatted.length).toBeLessThanOrEqual(MAX_SOURCE_UTF16_UNITS);
+    expect(formatted).toContain("[stdout]\n");
+    expect(formatted).toContain(`${MARKER}\n[${label}]\n`);
+    expect(formatted.split(`[${label}]\n`)).toHaveLength(2);
+    expect(formatted.endsWith("b")).toBe(true);
+  });
+
+  it("does not mistake stream-like text in single-stream output for a stream boundary", () => {
+    const formatted = formatExecApprovalContinuationSourceOutput([
+      { label: "stdout", value: `${"a".repeat(200_000)}\n[stderr]\n${"b".repeat(100_000)}` },
+    ]);
+
+    expect(formatted).not.toContain(`${MARKER}\n[stderr]\n`);
+  });
+
   it("uses an honest marker because capture may already have dropped output", () => {
     const formatted = formatExecApprovalContinuationSourceOutput([
       { label: "stdout", value: "z".repeat(MAX_SOURCE_UTF16_UNITS + 1) },
@@ -193,6 +220,25 @@ describe("resizeExecApprovalContinuationPrompt", () => {
     expect(resized.split(OUTPUT_BEGIN)).toHaveLength(2);
     expect(resized.split(OUTPUT_END)).toHaveLength(2);
   });
+
+  it("preserves the retained stream label when the resumed model applies its output budget", () => {
+    const output = formatExecApprovalContinuationSourceOutput([
+      { label: "stdout", value: "a".repeat(12_000) },
+      { label: "stderr", value: "b".repeat(10_000) },
+    ]);
+    const built = buildExecApprovalContinuationPrompt(
+      `Exec finished (node=node-1 id=approval-1, code 0)\n${output}`,
+    );
+    const resized = resizeExecApprovalContinuationPrompt({
+      prompt: built.message,
+      range: built.resultRange,
+      maxOutputUtf16Units: 16_000,
+    });
+
+    expect(resized).toContain(`${MARKER}\n[stderr]\n`);
+    expect(resized).toContain(OUTPUT_BEGIN);
+    expect(resized).toContain(OUTPUT_END);
+  });
 });
 
 describe("exec output rendering", () => {
diff --git a/src/agents/bash-tools.exec-approval-output.ts b/src/agents/bash-tools.exec-approval-output.ts
index b3ebf9fc5be0..27ee465a2c79 100644
--- a/src/agents/bash-tools.exec-approval-output.ts
+++ b/src/agents/bash-tools.exec-approval-output.ts
@@ -74,8 +74,18 @@ function capContinuationOutput(text: string, maxUtf16Units: number): string {
     return truncateUtf16Safe(TRUNCATION_MARKER, boundedMax);
   }
   const headBudget = Math.floor(cutBudget * HEAD_SHARE);
-  const head = alignHeadToLineBreak(truncateUtf16Safe(text, headBudget));
+  let head = alignHeadToLineBreak(truncateUtf16Safe(text, headBudget));
   const tail = alignTailToLineBreak(sliceUtf16Safe(text, text.length - (cutBudget - headBudget)));
+  // Recapping can omit a stream header while retaining its contents; restore its
+  // label from the omitted span so stderr/error never masquerades as stdout.
+  const omittedHeaders = /^\[(?:stdout|stderr|error)\]\n/m.test(head)
+    ? text.slice(head.length, text.length - tail.length).match(/^\[(?:stdout|stderr|error)\]\n/gm)
+    : null;
+  const tailHeader = omittedHeaders?.at(-1) ?? "";
+  if (tailHeader && tailHeader.length <= headBudget) {
+    head = alignHeadToLineBreak(truncateUtf16Safe(text, headBudget - tailHeader.length));
+    return `${head}\n${TRUNCATION_MARKER}\n${tailHeader}${tail}`;
+  }
   return `${head}\n${TRUNCATION_MARKER}\n${tail}`;
 }
 

From 69e4fbbeb5f800779e9b3f3c1a59527f77bfcf1f Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 14:33:10 -0700
Subject: [PATCH 101/124] fix(cli): tell operators a racing config set changed
 nothing (#127554)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When two config writes raced, the loser printed a bare "config changed
since last load" and exited 1 — no statement that its write was abandoned
and no hint that re-running works. The gateway sibling already says
"re-run config.get and retry".

Format ConfigMutationConflictError at handleConfigMutationError, the single
CLI boundary, so the low-level throw sites keep serving gateway and
programmatic callers unchanged. Dry-run JSON now reports kind "conflict"
instead of mislabelling a concurrency conflict as a schema error.

Concurrency control itself is unchanged: baseHash pinning and the retry
loop stay exactly as they were.
---
 docs/cli/config.md           |  2 +-
 src/cli/config-cli-runner.ts |  9 +++++--
 src/cli/config-cli.test.ts   | 48 ++++++++++++++++++++++++++++++++++++
 src/cli/config-set-dryrun.ts |  2 +-
 4 files changed, 57 insertions(+), 4 deletions(-)

diff --git a/docs/cli/config.md b/docs/cli/config.md
index 8f4d0a9bf114..f4925ca76f04 100644
--- a/docs/cli/config.md
+++ b/docs/cli/config.md
@@ -365,7 +365,7 @@ openclaw config set channels.discord.token \
     - `checks.resolvabilityComplete`: whether resolvability checks ran to completion (false when exec refs are skipped)
     - `refsChecked`: number of refs actually resolved during dry-run
     - `skippedExecRefs`: number of exec refs skipped because `--allow-exec` was not set
-    - `errors`: structured missing-path, schema, or resolvability failures when `ok=false`
+    - `errors`: structured failures when `ok=false`; each carries a `kind` of `missing-path`, `schema`, `resolvability`, `model`, or `conflict` (`conflict` means the config file changed while the command was writing, so nothing was changed — re-run to pick up the new file)
 
   </Accordion>
 </AccordionGroup>
diff --git a/src/cli/config-cli-runner.ts b/src/cli/config-cli-runner.ts
index 651c7e94e2b9..f3a0e9d8a86b 100644
--- a/src/cli/config-cli-runner.ts
+++ b/src/cli/config-cli-runner.ts
@@ -3,6 +3,7 @@ import { uniqueValues } from "@openclaw/normalization-core/string-normalization"
 import { replaceConfigFile } from "../config/config.js";
 import { AUTO_MANAGED_CONFIG_META_PATHS } from "../config/io.meta.js";
 import { formatConfigIssueLines } from "../config/issue-format.js";
+import { ConfigMutationConflictError } from "../config/mutation-conflict.js";
 import { resolveConfigPath } from "../config/paths.js";
 import { readBestEffortRuntimeConfigSchema } from "../config/runtime-schema.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
@@ -513,7 +514,11 @@ export function handleConfigMutationError(params: {
   runtime: RuntimeEnv;
   options: ConfigMutationOptions;
 }) {
-  const message = formatErrorMessage(params.err);
+  const isConflict = params.err instanceof ConfigMutationConflictError;
+  const detail = formatErrorMessage(params.err);
+  const message = isConflict
+    ? `The config file changed while this command was writing (${detail}), so nothing was changed. Re-run the same command to pick up the new file and try again.`
+    : detail;
   if (params.options.dryRun && params.options.json) {
     if (params.err instanceof ConfigSetDryRunValidationError) {
       writeRuntimeJson(params.runtime, params.err.result);
@@ -528,7 +533,7 @@ export function handleConfigMutationError(params: {
       checks: { schema: false, resolvability: false, resolvabilityComplete: false },
       refsChecked: 0,
       skippedExecRefs: 0,
-      errors: [{ kind: "schema", message }],
+      errors: [{ kind: isConflict ? "conflict" : "schema", message }],
     };
     writeRuntimeJson(params.runtime, result);
     params.runtime.error(danger(message));
diff --git a/src/cli/config-cli.test.ts b/src/cli/config-cli.test.ts
index 6b27d541ba06..b2d908fcde4d 100644
--- a/src/cli/config-cli.test.ts
+++ b/src/cli/config-cli.test.ts
@@ -5,6 +5,7 @@ import { Command } from "commander";
 // Config CLI tests cover config command registration, reads, writes, and output modes.
 import { createRequireRecord } from "openclaw/plugin-sdk/test-fixtures";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { ConfigMutationConflictError } from "../config/mutation-conflict.js";
 import type { ConfigFileSnapshot, OpenClawConfig } from "../config/types.js";
 import type { PluginManifestRecord, PluginManifestRegistry } from "../plugins/manifest-registry.js";
 import type { PluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js";
@@ -3373,6 +3374,53 @@ describe("config cli", () => {
       expectErrorIncludes("Dry run failed: 1 SecretRef assignment(s) could not be resolved.");
     });
 
+    it("explains config mutation conflicts without changing the exit code", async () => {
+      mockWriteConfigFile.mockRejectedValueOnce(
+        new ConfigMutationConflictError("included config changed since last load"),
+      );
+
+      await expect(runConfigSet("gateway.port", "19000")).rejects.toThrow(ExitError);
+
+      expect(mockExit).toHaveBeenCalledWith(1);
+      expectErrorIncludes(
+        "The config file changed while this command was writing (included config changed since last load), so nothing was changed. Re-run the same command to pick up the new file and try again.",
+      );
+    });
+
+    it("reports config mutation conflicts accurately in dry-run JSON", async () => {
+      mockReadConfigFileSnapshot.mockRejectedValueOnce(
+        new ConfigMutationConflictError("config changed since last load"),
+      );
+
+      await expect(
+        runConfigCommand(["config", "set", "gateway.port", "19000", "--dry-run", "--json"]),
+      ).rejects.toThrow(ExitError);
+
+      expect(mockExit).toHaveBeenCalledWith(1);
+      expect(parseLastLogPayload()).toMatchObject({
+        ok: false,
+        errors: [
+          {
+            kind: "conflict",
+            message:
+              "The config file changed while this command was writing (config changed since last load), so nothing was changed. Re-run the same command to pick up the new file and try again.",
+          },
+        ],
+      });
+    });
+
+    it("preserves non-conflict config mutation errors", async () => {
+      mockWriteConfigFile.mockRejectedValueOnce(new Error("permission denied"));
+
+      await expect(runConfigSet("gateway.port", "19000")).rejects.toThrow(ExitError);
+
+      expect(mockExit).toHaveBeenCalledWith(1);
+      expectErrorIncludes("permission denied");
+      expect(mockError.mock.calls.flat().join("\n")).not.toContain(
+        "The config file changed while this command was writing",
+      );
+    });
+
     it("emits structured JSON for --dry-run --json success", async () => {
       setGatewaySnapshot({ providers: { default: { source: "env" } } });
 
diff --git a/src/cli/config-set-dryrun.ts b/src/cli/config-set-dryrun.ts
index c9f3cf62c13e..cffac1d783ee 100644
--- a/src/cli/config-set-dryrun.ts
+++ b/src/cli/config-set-dryrun.ts
@@ -4,7 +4,7 @@ export type ConfigSetDryRunInputMode = "value" | "json" | "builder" | "unset";
 
 /** One validation error found during config-set dry-run processing. */
 export type ConfigSetDryRunError = {
-  kind: "missing-path" | "schema" | "resolvability" | "model";
+  kind: "missing-path" | "schema" | "resolvability" | "model" | "conflict";
   message: string;
   ref?: string;
 };

From 9dc42007a709b1632643f33799e0a53e481b1acb Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 14:43:35 -0700
Subject: [PATCH 102/124] fix(cli): stop approvals --json printing the
 exec-approvals socket token (#127610)

approvals get --json and every local approvals write emitted
file.socket.token in clear text, while the gateway RPC, the node-host RPC,
and the state snapshot sanitizer all strip it, and the human-readable table
shows only the socket path.

The token is root key material: operator-approval-runtime-token.ts HMACs it
to authorize local operator-approval clients, and agent-runtime-identity-token.ts
reads it for the agent runtime identity token.

Promote one canonical redactExecApprovals to src/infra/exec-approvals.ts,
retire the two duplicate copies, and apply it to the local CLI JSON paths.
It also drops the snapshot's raw field, which carried the same token as
stored JSON.
---
 src/cli/exec-approvals-cli.test.ts           | 33 ++++++++++++++++++++
 src/cli/exec-approvals-cli.ts                |  6 ++--
 src/gateway/server-methods/exec-approvals.ts | 16 ++--------
 src/infra/exec-approvals.ts                  | 21 ++++++++++++-
 src/node-host/invoke.ts                      | 21 ++-----------
 5 files changed, 62 insertions(+), 35 deletions(-)

diff --git a/src/cli/exec-approvals-cli.test.ts b/src/cli/exec-approvals-cli.test.ts
index e3f94146ec48..cbc18dc2a120 100644
--- a/src/cli/exec-approvals-cli.test.ts
+++ b/src/cli/exec-approvals-cli.test.ts
@@ -170,6 +170,7 @@ function scopeByLabel(label: string, output: Record<string, unknown> = writtenJs
 
 function resetLocalSnapshot() {
   localSnapshot.exists = true;
+  localSnapshot.raw = "{}";
   localSnapshot.hash = "hash-local";
   localSnapshot.file = { version: 1, agents: {} };
 }
@@ -220,6 +221,7 @@ vi.mock("../infra/exec-approvals.js", async () => {
         const next = update(structuredClone(localSnapshot.file));
         if (next !== null) {
           localSnapshot.file = next;
+          localSnapshot.raw = JSON.stringify(next);
           localSnapshot.hash = "hash-local-written";
         }
         return structuredClone(localSnapshot);
@@ -353,6 +355,37 @@ describe("exec approvals CLI", () => {
     expect(requireRecord(allowlist[0], "JSON allowlist entry").pattern).toBe(pattern);
   });
 
+  it("redacts the socket token from local get JSON while preserving its path", async () => {
+    localSnapshot.file = {
+      version: 1,
+      socket: { path: "/tmp/local-exec-approvals.sock", token: "fixture-token" },
+      agents: {},
+    };
+
+    await runApprovalsCommand(["approvals", "get", "--json"]);
+
+    const output = writtenJson();
+    const file = requireRecord(output.file, "JSON approvals file");
+    expect(file.socket).toEqual({ path: "/tmp/local-exec-approvals.sock" });
+    expect(JSON.stringify(output)).not.toContain('"token"');
+  });
+
+  it("redacts the socket token from local write JSON while preserving its path", async () => {
+    localSnapshot.file = {
+      version: 1,
+      socket: { path: "/tmp/local-exec-approvals.sock", token: "fixture-token" },
+      agents: {},
+    };
+
+    await runApprovalsCommand(["approvals", "allowlist", "add", "/usr/bin/uname", "--json"]);
+
+    const output = writtenJson();
+    const file = requireRecord(output.file, "JSON approvals file");
+    expect(file.socket).toEqual({ path: "/tmp/local-exec-approvals.sock" });
+    expect(output.raw).toBeUndefined();
+    expect(JSON.stringify(output)).not.toContain('"token"');
+  });
+
   it("adds effective policy to json output", async () => {
     localSnapshot.file = {
       version: 1,
diff --git a/src/cli/exec-approvals-cli.ts b/src/cli/exec-approvals-cli.ts
index ba935028f74e..49e8400e6cce 100644
--- a/src/cli/exec-approvals-cli.ts
+++ b/src/cli/exec-approvals-cli.ts
@@ -36,6 +36,7 @@ import {
   mergeExecApprovalsSocketDefaults,
   normalizeExecApprovals,
   readExecApprovalsSnapshot,
+  redactExecApprovals,
   updateExecApprovals,
   type ExecApprovalsAgent,
   type ExecApprovalsDefaults,
@@ -368,7 +369,7 @@ async function saveSnapshotTargeted(params: SaveSnapshotTargetedParams): Promise
     next = await saveSnapshot(params.opts, params.nodeId, params.file, params.baseHash);
   }
   if (params.opts.json) {
-    defaultRuntime.writeJson(next, 0);
+    defaultRuntime.writeJson(isFileApprovalsSnapshot(next) ? redactExecApprovals(next) : next, 0);
     return;
   }
   defaultRuntime.log(theme.muted(`Target: ${params.targetLabel}`));
@@ -1188,7 +1189,8 @@ export function registerExecApprovalsCli(program: Command) {
           nativePolicy,
         });
         if (opts.json) {
-          defaultRuntime.writeJson({ ...snapshot, effectivePolicy }, 0);
+          const outputSnapshot = fileSnapshot ? redactExecApprovals(fileSnapshot) : snapshot;
+          defaultRuntime.writeJson({ ...outputSnapshot, effectivePolicy }, 0);
           return;
         }
 
diff --git a/src/gateway/server-methods/exec-approvals.ts b/src/gateway/server-methods/exec-approvals.ts
index fb8e81d9808b..34c5986edeed 100644
--- a/src/gateway/server-methods/exec-approvals.ts
+++ b/src/gateway/server-methods/exec-approvals.ts
@@ -18,6 +18,7 @@ import {
   mergeExecApprovalsSocketDefaults,
   normalizeExecApprovals,
   readExecApprovalsSnapshot,
+  redactExecApprovals,
   resolveExecApprovalsFromFile,
   updateExecApprovals,
   type ExecApprovalsFile,
@@ -89,22 +90,9 @@ function respondApprovalsChanged(respond: RespondFn): void {
   );
 }
 
-function redactExecApprovals(file: ExecApprovalsFile): ExecApprovalsFile {
-  const socketPath = file.socket?.path?.trim();
-  // The socket token/defaults are runtime-only; expose only the path needed by
-  // the editor so GET responses cannot leak connection material.
-  return {
-    ...file,
-    socket: socketPath ? { path: socketPath } : undefined,
-  };
-}
-
 function toExecApprovalsPayload(snapshot: ExecApprovalsSnapshot) {
   return {
-    path: snapshot.path,
-    exists: snapshot.exists,
-    hash: snapshot.hash,
-    file: redactExecApprovals(snapshot.file),
+    ...redactExecApprovals(snapshot),
     resolvedDefaults: resolveExecApprovalsFromFile({ file: snapshot.file }).defaults,
   };
 }
diff --git a/src/infra/exec-approvals.ts b/src/infra/exec-approvals.ts
index 61d9c2855616..1511b5bf8a16 100644
--- a/src/infra/exec-approvals.ts
+++ b/src/infra/exec-approvals.ts
@@ -5,7 +5,11 @@ import {
   resolveExecApprovalsSocketPath,
 } from "./exec-approvals-config.js";
 import type { ExecApprovalsDefaultOverrides } from "./exec-approvals-contracts.js";
-import type { ExecApprovalsFile, ExecApprovalsResolved } from "./exec-approvals-core.js";
+import type {
+  ExecApprovalsFile,
+  ExecApprovalsResolved,
+  ExecApprovalsSnapshot,
+} from "./exec-approvals-core.js";
 import { resolveExecApprovalsFromFilePrepared } from "./exec-approvals-resolver.js";
 import {
   ensureExecApprovals,
@@ -42,6 +46,21 @@ export {
   withAgentExecApprovalsRemoved,
 } from "./exec-approvals-store.js";
 
+export function redactExecApprovals(
+  snapshot: Omit<ExecApprovalsSnapshot, "raw"> & { raw?: ExecApprovalsSnapshot["raw"] },
+): Omit<ExecApprovalsSnapshot, "raw"> {
+  const { raw: _raw, ...rest } = snapshot;
+  const socketPath = snapshot.file.socket?.path?.trim();
+  // Socket connection material is runtime-only; presentation boundaries need only its path.
+  return {
+    ...rest,
+    file: {
+      ...snapshot.file,
+      socket: socketPath ? { path: socketPath } : undefined,
+    },
+  };
+}
+
 export function normalizeExecApprovals(file: ExecApprovalsFile): ExecApprovalsFile {
   const socketPath = file.socket?.path?.trim();
   const token = file.socket?.token?.trim();
diff --git a/src/node-host/invoke.ts b/src/node-host/invoke.ts
index e0bd38cd60ff..248f62ba35f8 100644
--- a/src/node-host/invoke.ts
+++ b/src/node-host/invoke.ts
@@ -12,6 +12,7 @@ import {
   mergeExecApprovalsSocketDefaults,
   normalizeExecApprovals,
   readExecApprovalsSnapshot,
+  redactExecApprovals,
   resolveAllowAlwaysPatternCoverage,
   resolveExecApprovalsFromFile,
   updateExecApprovals,
@@ -274,14 +275,6 @@ function truncateOutput(raw: string, maxChars: number): { text: string; truncate
   return { text: `... (truncated) ${sliceUtf16Safe(raw, raw.length - maxChars)}`, truncated: true };
 }
 
-function redactExecApprovals(file: ExecApprovalsFile): ExecApprovalsFile {
-  const socketPath = file.socket?.path?.trim();
-  return {
-    ...file,
-    socket: socketPath ? { path: socketPath } : undefined,
-  };
-}
-
 function requireExecApprovalsBaseHash(
   params: SystemExecApprovalsSetParams,
   snapshot: ExecApprovalsSnapshot,
@@ -692,10 +685,7 @@ async function dispatchInvoke(
     try {
       const snapshot = await ensureExecApprovalsSnapshot();
       const payload = {
-        path: snapshot.path,
-        exists: snapshot.exists,
-        hash: snapshot.hash,
-        file: redactExecApprovals(snapshot.file),
+        ...redactExecApprovals(snapshot),
         ...(includeResolvedDefaults
           ? { resolvedDefaults: resolveExecApprovalsFromFile({ file: snapshot.file }).defaults }
           : {}),
@@ -758,12 +748,7 @@ async function dispatchInvoke(
       return;
     }
 
-    const payload: ExecApprovalsSnapshot = {
-      path: nextSnapshot.path,
-      exists: nextSnapshot.exists,
-      hash: nextSnapshot.hash,
-      file: redactExecApprovals(nextSnapshot.file),
-    };
+    const payload: ExecApprovalsSnapshot = redactExecApprovals(nextSnapshot);
     await sendJsonPayloadResult(client, frame, payload);
     return;
   }

From 9b98e7b193927ec5031f152e606545217f8ab2d4 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 14:46:21 -0700
Subject: [PATCH 103/124] fix(agents): preserve real user turns during
 compaction (#127563)

---
 ...compaction-duplicate-user-messages.test.ts | 79 +++++++++++++++++++
 .../compaction-duplicate-user-messages.ts     | 18 ++++-
 2 files changed, 93 insertions(+), 4 deletions(-)

diff --git a/src/agents/embedded-agent-runner/compaction-duplicate-user-messages.test.ts b/src/agents/embedded-agent-runner/compaction-duplicate-user-messages.test.ts
index 459e3aa9048e..a0bd2604ffc6 100644
--- a/src/agents/embedded-agent-runner/compaction-duplicate-user-messages.test.ts
+++ b/src/agents/embedded-agent-runner/compaction-duplicate-user-messages.test.ts
@@ -73,6 +73,85 @@ describe("compaction duplicate user message pruning", () => {
     ]);
   });
 
+  it.each([
+    {
+      name: "a completed assistant reply",
+      completedTurn: [
+        { role: "assistant", content: [{ type: "text", text: "first reply" }], timestamp: 1_500 },
+      ],
+    },
+    {
+      name: "an assistant tool call and its result",
+      completedTurn: [
+        {
+          role: "assistant",
+          content: [{ type: "toolCall", id: "call-1", name: "read", arguments: {} }],
+          timestamp: 1_500,
+        },
+        {
+          role: "toolResult",
+          toolCallId: "call-1",
+          content: [{ type: "text", text: "read complete" }],
+          timestamp: 1_750,
+        },
+      ],
+    },
+  ])("preserves the same user request after $name", ({ completedTurn }) => {
+    const first = userMessage({ timestamp: 1_000 });
+    const next = userMessage({ timestamp: 2_000 });
+    const messages = [first, ...completedTurn, next];
+
+    expect(dedupeDuplicateUserMessagesForCompaction(messages)).toEqual(messages);
+  });
+
+  it.each([
+    { name: "images", kind: "image", extension: "png" },
+    { name: "videos", kind: "video", extension: "mp4" },
+    { name: "documents", kind: "document", extension: "pdf" },
+  ])("preserves separately attached $name with the same caption", ({ kind, extension }) => {
+    const first = {
+      ...userMessage({ timestamp: 1_000 }),
+      __openclaw: { media: [{ kind, url: `media://inbound/first.${extension}` }] },
+    };
+    const second = {
+      ...userMessage({ timestamp: 2_000 }),
+      __openclaw: { media: [{ kind, url: `media://inbound/second.${extension}` }] },
+    };
+
+    expect(dedupeDuplicateUserMessagesForCompaction([first, second])).toEqual([first, second]);
+  });
+
+  it("preserves an attachment added to a previously text-only request", () => {
+    const first = userMessage({ timestamp: 1_000 });
+    const second = {
+      ...userMessage({ timestamp: 2_000 }),
+      __openclaw: { media: [{ kind: "image", url: "media://inbound/diagram.png" }] },
+    };
+
+    expect(dedupeDuplicateUserMessagesForCompaction([first, second])).toEqual([first, second]);
+  });
+
+  it("preserves prompts with distinct case-sensitive paths", () => {
+    const first = userMessage({
+      timestamp: 1_000,
+      content: "please inspect /srv/Production/ReleaseNotes.md",
+    });
+    const second = userMessage({
+      timestamp: 2_000,
+      content: "please inspect /srv/production/releasenotes.md",
+    });
+
+    expect(dedupeDuplicateUserMessagesForCompaction([first, second])).toEqual([first, second]);
+  });
+
+  it("preserves older requests without losing the newest retry timestamp", () => {
+    const newer = userMessage({ timestamp: 120_000 });
+    const older = userMessage({ timestamp: 1_000 });
+    const retry = userMessage({ timestamp: 121_000 });
+
+    expect(dedupeDuplicateUserMessagesForCompaction([newer, older, retry])).toEqual([newer, older]);
+  });
+
   it("does not collide when sender ids and text contain the old delimiter", () => {
     const first = userMessage({
       content: "b|please run deployment status now",
diff --git a/src/agents/embedded-agent-runner/compaction-duplicate-user-messages.ts b/src/agents/embedded-agent-runner/compaction-duplicate-user-messages.ts
index 8a45b6643a00..72e57d53d6d2 100644
--- a/src/agents/embedded-agent-runner/compaction-duplicate-user-messages.ts
+++ b/src/agents/embedded-agent-runner/compaction-duplicate-user-messages.ts
@@ -2,6 +2,7 @@
  * Removes short-window duplicate user turns from compaction summaries.
  */
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
+import { hasPersistedMedia } from "../../sessions/user-turn-media.js";
 
 const DEFAULT_DUPLICATE_USER_MESSAGE_WINDOW_MS = 60_000;
 const MIN_DUPLICATE_USER_MESSAGE_CHARS = 24;
@@ -44,7 +45,7 @@ function duplicateSignature(message: unknown): { key: string; timestamp: number
     return undefined;
   }
   const text = normalizeUserMessageContent(message.content);
-  if (!text || text.length < MIN_DUPLICATE_USER_MESSAGE_CHARS) {
+  if (!text || text.length < MIN_DUPLICATE_USER_MESSAGE_CHARS || hasPersistedMedia(message)) {
     return undefined;
   }
   // Persisted sender identity keeps distinct participants separate while senderless legacy
@@ -53,7 +54,7 @@ function duplicateSignature(message: unknown): { key: string; timestamp: number
   const senderId =
     isRecord(metadata) && typeof metadata.senderId === "string" ? metadata.senderId : "";
   return {
-    key: JSON.stringify([senderId, text.normalize("NFC").toLowerCase()]),
+    key: JSON.stringify([senderId, text.normalize("NFC")]),
     timestamp: message.timestamp,
   };
 }
@@ -70,12 +71,21 @@ export function dedupeDuplicateUserMessagesForCompaction<T extends MessageLike>(
   for (const message of messages) {
     const signature = duplicateSignature(message);
     if (!signature) {
+      // A reply ends the retry batch; identical later asks are real user turns.
+      if (message.role === "assistant") {
+        lastSeenAtByKey.clear();
+      }
       result.push(message);
       continue;
     }
     const lastSeenAt = lastSeenAtByKey.get(signature.key);
-    lastSeenAtByKey.set(signature.key, signature.timestamp);
-    if (typeof lastSeenAt === "number" && signature.timestamp - lastSeenAt <= windowMs) {
+    const newestTimestamp = Math.max(lastSeenAt ?? signature.timestamp, signature.timestamp);
+    lastSeenAtByKey.set(signature.key, newestTimestamp);
+    if (
+      typeof lastSeenAt === "number" &&
+      signature.timestamp >= lastSeenAt &&
+      signature.timestamp - lastSeenAt <= windowMs
+    ) {
       // Keep the first prompt and drop only later repeats. The first copy anchors the summarized
       // branch while duplicate retries no longer inflate compaction context.
       removed += 1;

From 76254431958798b3b66f0bb16c009d59a0d8d225 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 14:46:59 -0700
Subject: [PATCH 104/124] fix(macos): fence stale Gateway connection-mode
 transitions (#127609)

---
 .../OpenClaw/ConnectionModeCoordinator.swift  | 114 ++++++++++--------
 .../Sources/OpenClaw/ControlChannel.swift     |   4 +-
 .../macos/Sources/OpenClaw/DebugActions.swift |   1 -
 .../ConnectionModeCoordinatorTests.swift      |  31 +++++
 4 files changed, 97 insertions(+), 53 deletions(-)
 create mode 100644 apps/macos/Tests/OpenClawIPCTests/ConnectionModeCoordinatorTests.swift

diff --git a/apps/macos/Sources/OpenClaw/ConnectionModeCoordinator.swift b/apps/macos/Sources/OpenClaw/ConnectionModeCoordinator.swift
index fc476e4f0780..fe576b5a079b 100644
--- a/apps/macos/Sources/OpenClaw/ConnectionModeCoordinator.swift
+++ b/apps/macos/Sources/OpenClaw/ConnectionModeCoordinator.swift
@@ -5,67 +5,51 @@ import OSLog
 final class ConnectionModeCoordinator {
     static let shared = ConnectionModeCoordinator()
 
+    struct Transition {
+        private(set) var generation: UInt64 = 0
+        private(set) var mode: AppState.ConnectionMode?
+
+        mutating func begin(_ mode: AppState.ConnectionMode) -> UInt64 {
+            self.generation &+= 1
+            self.mode = mode
+            return self.generation
+        }
+
+        func isCurrent(_ generation: UInt64, mode: AppState.ConnectionMode) -> Bool {
+            self.generation == generation && self.mode == mode
+        }
+    }
+
     private let logger = Logger(subsystem: "ai.openclaw", category: "connection")
-    private var lastMode: AppState.ConnectionMode?
-    private var applyGeneration: UInt64 = 0
+    private var transition = Transition()
 
     /// Apply the requested connection mode by starting/stopping local gateway,
     /// managing the control-channel SSH tunnel, and cleaning up chat windows/panels.
     func apply(mode: AppState.ConnectionMode, paused: Bool) async {
-        self.applyGeneration &+= 1
-        let applyGeneration = self.applyGeneration
-        if let lastMode = self.lastMode, lastMode != mode {
+        let previousMode = self.transition.mode
+        let applyGeneration = self.transition.begin(mode)
+        if let previousMode, previousMode != mode {
             GatewayProcessManager.shared.clearLastFailure()
             NodesStore.shared.lastError = nil
         }
-        self.lastMode = mode
+        if mode != .remote {
+            _ = await NodeServiceManager.stop()
+            guard self.transition.isCurrent(applyGeneration, mode: mode) else { return }
+            NodesStore.shared.lastError = nil
+            await RemoteTunnelManager.shared.stopAll()
+            guard self.transition.isCurrent(applyGeneration, mode: mode) else { return }
+            WebChatManager.shared.resetTunnels()
+        }
+
         switch mode {
         case .unconfigured:
-            _ = await NodeServiceManager.stop()
-            NodesStore.shared.lastError = nil
-            await RemoteTunnelManager.shared.stopAll()
-            WebChatManager.shared.resetTunnels()
             GatewayProcessManager.shared.stop()
-            await GatewayConnection.shared.shutdown()
             await ControlChannel.shared.disconnect()
-            Task.detached { await PortGuardian.shared.sweep(mode: .unconfigured) }
+            guard self.transition.isCurrent(applyGeneration, mode: mode) else { return }
 
         case .local:
-            _ = await NodeServiceManager.stop()
-            guard self.applyGeneration == applyGeneration else { return }
-            NodesStore.shared.lastError = nil
-            await RemoteTunnelManager.shared.stopAll()
-            guard self.applyGeneration == applyGeneration else { return }
-            WebChatManager.shared.resetTunnels()
-            let shouldStart = GatewayAutostartPolicy.shouldStartGateway(mode: .local, paused: paused)
-            if shouldStart {
-                GatewayProcessManager.shared.setActive(true)
-                await GatewayProcessManager.shared.waitForStartupAttempt()
-                guard self.applyGeneration == applyGeneration else { return }
-                var launchAgentInstalled = false
-                if GatewayAutostartPolicy.shouldEnsureLaunchAgent(
-                    mode: .local,
-                    paused: paused)
-                {
-                    launchAgentInstalled = await GatewayProcessManager.shared.ensureLaunchAgentEnabledIfNeeded()
-                }
-                guard self.applyGeneration == applyGeneration else { return }
-                // Always finish the generation-aware health audit after persistence work. A newer
-                // inactive lifecycle makes this return false without touching its repair marker.
-                _ = await GatewayProcessManager.shared.waitForGatewayReady(
-                    launchAgentInstalled: launchAgentInstalled)
-                guard self.applyGeneration == applyGeneration else { return }
-            } else {
-                GatewayProcessManager.shared.stop()
-            }
-            do {
-                try await ControlChannel.shared.configure(mode: .local)
-            } catch {
-                // Control channel will mark itself degraded; nothing else to do here.
-                self.logger.error(
-                    "control channel local configure failed: \(error.localizedDescription, privacy: .public)")
-            }
-            Task.detached { await PortGuardian.shared.sweep(mode: .local) }
+            await self.applyLocalMode(paused: paused, generation: applyGeneration)
+            guard self.transition.isCurrent(applyGeneration, mode: mode) else { return }
 
         case .remote:
             // Never run a local gateway in remote mode.
@@ -74,19 +58,51 @@ final class ConnectionModeCoordinator {
 
             do {
                 NodesStore.shared.lastError = nil
-                if let error = await NodeServiceManager.start() {
+                let nodeError = await NodeServiceManager.start()
+                guard self.transition.isCurrent(applyGeneration, mode: mode) else { return }
+                if let error = nodeError {
                     NodesStore.shared.lastError = "Node service start failed: \(error)"
                 }
                 _ = try await GatewayEndpointStore.shared.ensureRemoteControlTunnel()
+                guard self.transition.isCurrent(applyGeneration, mode: mode) else { return }
                 let settings = CommandResolver.connectionSettings()
                 try await ControlChannel.shared.configure(mode: .remote(
                     target: settings.target,
                     identity: settings.identity))
+                guard self.transition.isCurrent(applyGeneration, mode: mode) else { return }
             } catch {
+                guard self.transition.isCurrent(applyGeneration, mode: mode) else { return }
                 self.logger.error("remote tunnel/configure failed: \(error.localizedDescription, privacy: .public)")
             }
+        }
 
-            Task.detached { await PortGuardian.shared.sweep(mode: .remote) }
+        Task.detached { await PortGuardian.shared.sweep(mode: mode) }
+    }
+
+    private func applyLocalMode(paused: Bool, generation: UInt64) async {
+        if GatewayAutostartPolicy.shouldStartGateway(mode: .local, paused: paused) {
+            GatewayProcessManager.shared.setActive(true)
+            await GatewayProcessManager.shared.waitForStartupAttempt()
+            guard self.transition.isCurrent(generation, mode: .local) else { return }
+            var launchAgentInstalled = false
+            if GatewayAutostartPolicy.shouldEnsureLaunchAgent(mode: .local, paused: paused) {
+                launchAgentInstalled = await GatewayProcessManager.shared.ensureLaunchAgentEnabledIfNeeded()
+            }
+            guard self.transition.isCurrent(generation, mode: .local) else { return }
+            // Finish persistence before readiness so a newer lifecycle cannot clear its repair marker.
+            _ = await GatewayProcessManager.shared.waitForGatewayReady(
+                launchAgentInstalled: launchAgentInstalled)
+            guard self.transition.isCurrent(generation, mode: .local) else { return }
+        } else {
+            GatewayProcessManager.shared.stop()
+        }
+
+        do {
+            try await ControlChannel.shared.configure(mode: .local)
+        } catch {
+            guard self.transition.isCurrent(generation, mode: .local) else { return }
+            self.logger.error(
+                "control channel local configure failed: \(error.localizedDescription, privacy: .public)")
         }
     }
 }
diff --git a/apps/macos/Sources/OpenClaw/ControlChannel.swift b/apps/macos/Sources/OpenClaw/ControlChannel.swift
index 422d69a59096..4af96725f643 100644
--- a/apps/macos/Sources/OpenClaw/ControlChannel.swift
+++ b/apps/macos/Sources/OpenClaw/ControlChannel.swift
@@ -217,10 +217,8 @@ final class ControlChannel {
     }
 
     func disconnect() async {
-        await GatewayConnection.shared.shutdown()
         self.setStateThrottled(.disconnected)
-        self.lastPingMs = nil
-        self.authSourceLabel = nil
+        await GatewayConnection.shared.shutdown()
     }
 
     func health(timeout: TimeInterval? = nil) async throws -> Data {
diff --git a/apps/macos/Sources/OpenClaw/DebugActions.swift b/apps/macos/Sources/OpenClaw/DebugActions.swift
index 18c3c796b7e2..8d0ffab346c8 100644
--- a/apps/macos/Sources/OpenClaw/DebugActions.swift
+++ b/apps/macos/Sources/OpenClaw/DebugActions.swift
@@ -108,7 +108,6 @@ enum DebugActions {
                 }
 
             case .unconfigured:
-                await GatewayConnection.shared.shutdown()
                 await ControlChannel.shared.disconnect()
             }
         }
diff --git a/apps/macos/Tests/OpenClawIPCTests/ConnectionModeCoordinatorTests.swift b/apps/macos/Tests/OpenClawIPCTests/ConnectionModeCoordinatorTests.swift
new file mode 100644
index 000000000000..1127b713653e
--- /dev/null
+++ b/apps/macos/Tests/OpenClawIPCTests/ConnectionModeCoordinatorTests.swift
@@ -0,0 +1,31 @@
+import Testing
+@testable import OpenClaw
+
+@MainActor
+struct ConnectionModeCoordinatorTests {
+    @Test(arguments: [
+        (AppState.ConnectionMode.unconfigured, AppState.ConnectionMode.local),
+        (AppState.ConnectionMode.remote, AppState.ConnectionMode.local),
+        (AppState.ConnectionMode.local, AppState.ConnectionMode.remote),
+    ])
+    func `newer connection mode owns transition side effects`(
+        previousMode: AppState.ConnectionMode,
+        nextMode: AppState.ConnectionMode)
+    {
+        var transition = ConnectionModeCoordinator.Transition()
+        let previousGeneration = transition.begin(previousMode)
+        let currentGeneration = transition.begin(nextMode)
+
+        #expect(!transition.isCurrent(previousGeneration, mode: previousMode))
+        #expect(transition.isCurrent(currentGeneration, mode: nextMode))
+    }
+
+    @Test func `reselecting the same mode invalidates its prior transition`() {
+        var transition = ConnectionModeCoordinator.Transition()
+        let previousGeneration = transition.begin(.remote)
+        let currentGeneration = transition.begin(.remote)
+
+        #expect(!transition.isCurrent(previousGeneration, mode: .remote))
+        #expect(transition.isCurrent(currentGeneration, mode: .remote))
+    }
+}

From f95443125be6f61e980c26128e9ea7b448d243f3 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 14:48:42 -0700
Subject: [PATCH 105/124] fix(ui): separate settings footer actions from build
 info (#127597)

Amp-Thread-ID: https://ampcode.com/threads/T-01a021f4-b547-7788-a916-d4a94cbd3e3b

Co-authored-by: Amp <amp@ampcode.com>
---
 ui/src/e2e/config-safe-write.e2e.test.ts | 47 +++++++++++++++++++++++-
 ui/src/styles/layout.css                 |  7 +++-
 2 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/ui/src/e2e/config-safe-write.e2e.test.ts b/ui/src/e2e/config-safe-write.e2e.test.ts
index 6270ae3827b1..de639d3fe4a3 100644
--- a/ui/src/e2e/config-safe-write.e2e.test.ts
+++ b/ui/src/e2e/config-safe-write.e2e.test.ts
@@ -111,6 +111,21 @@ function settingsRow(page: Page, title: string): Locator {
   });
 }
 
+function overlapArea(
+  first: { x: number; y: number; width: number; height: number },
+  second: { x: number; y: number; width: number; height: number },
+): number {
+  const width = Math.max(
+    0,
+    Math.min(first.x + first.width, second.x + second.width) - Math.max(first.x, second.x),
+  );
+  const height = Math.max(
+    0,
+    Math.min(first.y + first.height, second.y + second.height) - Math.max(first.y, second.y),
+  );
+  return width * height;
+}
+
 async function capture(page: Page, name: string): Promise<void> {
   if (!captureUiProofEnabled) {
     return;
@@ -440,10 +455,40 @@ suite.define(() => {
         await expect
           .poll(() => saveIndicator.textContent())
           .toContain("Autosave paused after reconnect");
+        const saveButton = saveIndicator.getByRole("button", { name: "Save", exact: true });
+        const buildLink = page.locator(".settings-sidebar__footer .sidebar-footer-build");
+        await saveButton.focus();
+        await expect
+          .poll(() => saveButton.evaluate((element) => element === document.activeElement))
+          .toBe(true);
+        const [saveBounds, buildBounds] = await Promise.all([
+          saveButton.boundingBox(),
+          buildLink.boundingBox(),
+        ]);
+        expect(saveBounds).not.toBeNull();
+        expect(buildBounds).not.toBeNull();
+        if (!saveBounds || !buildBounds) {
+          throw new Error("Expected visible settings footer controls");
+        }
+        expect(overlapArea(saveBounds, buildBounds)).toBe(0);
+        expect(await buildLink.textContent()).not.toBe("");
         await capture(page, "07-opaque-revision-reconnect.png");
 
+        await page.setViewportSize({ height: 900, width: 1280 });
+        const [narrowSaveBounds, narrowBuildBounds] = await Promise.all([
+          saveButton.boundingBox(),
+          buildLink.boundingBox(),
+        ]);
+        expect(narrowSaveBounds).not.toBeNull();
+        expect(narrowBuildBounds).not.toBeNull();
+        if (!narrowSaveBounds || !narrowBuildBounds) {
+          throw new Error("Expected visible settings footer controls at 1280px");
+        }
+        expect(overlapArea(narrowSaveBounds, narrowBuildBounds)).toBe(0);
+        await capture(page, "07-opaque-revision-reconnect-1280.png");
+
         await gateway.deferNext("config.set");
-        await saveIndicator.getByRole("button", { name: "Save", exact: true }).click();
+        await saveButton.click();
         const save = mutationParams(await gateway.waitForRequest("config.set"));
         expect(save.baseHash).toBe("hmac-sha256:v1:opaque-current");
         expect(JSON.parse(String(save.raw))).toMatchObject({
diff --git a/ui/src/styles/layout.css b/ui/src/styles/layout.css
index 89beeb96c1b3..fd14aad45ccc 100644
--- a/ui/src/styles/layout.css
+++ b/ui/src/styles/layout.css
@@ -616,7 +616,8 @@ html.openclaw-native-web-chrome .shell-chrome-controls {
 .settings-sidebar__footer {
   flex-shrink: 0;
   display: flex;
-  align-items: center;
+  flex-direction: column;
+  align-items: stretch;
   gap: 8px;
   padding: 12px 21px;
   border-top: 1px solid color-mix(in srgb, var(--border) 80%, transparent);
@@ -628,6 +629,10 @@ openclaw-settings-save-indicator {
   min-width: 0;
 }
 
+openclaw-settings-save-indicator:empty {
+  display: none;
+}
+
 .settings-save-indicator {
   display: flex;
   align-items: center;

From 75b736c2526305b78b4bef1cebc9691a264a041b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 14:49:05 -0700
Subject: [PATCH 106/124] test(runner): reset console routing between
 non-isolated files (#127604)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

enableConsoleCapture() replaces every console method with a forwarder and
routeLogsToStderr()/`--json` mode latch loggingState.forceConsoleToStderr,
which production only unwinds at process exit. loggingState is keyed off
globalThis so it survives vi.resetModules(), so a shared Vitest worker carried
both into the next file: the inherited forwarder writes to process.stderr and
the next file's console.error spy records nothing.

That is the source of the order-dependent
`src/entry.run-main.test.ts > keeps expected conditions at exit 1` flake in
shard core-unit-src-security-2 — it failed only on workers that ran
src/mcp/codex-supervision-tools-serve.test.ts (serveCodexSupervisionToolsMcp
-> routeLogsToStderr) first.

Restore the worker's baseline console methods and logging state in the
runner's existing cross-file cleanup, and drop the two consumer-side
workarounds that were compensating for it.
---
 src/entry.run-main.test.ts                    |  2 -
 src/mcp/codex-supervision-tools-serve.test.ts |  9 +----
 test/non-isolated-runner.test.ts              | 37 ++++++++++++++++++-
 test/non-isolated-runner.ts                   | 26 +++++++++++++
 4 files changed, 63 insertions(+), 11 deletions(-)

diff --git a/src/entry.run-main.test.ts b/src/entry.run-main.test.ts
index 597f41ed34d1..ec5a383ff742 100644
--- a/src/entry.run-main.test.ts
+++ b/src/entry.run-main.test.ts
@@ -1,7 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import { ExpectedCliError } from "./cli/failure-output.js";
 import { runMainOrRootHelp } from "./entry.js";
-import { enableConsoleCapture } from "./logging.js";
 
 describe("entry run-main boundary", () => {
   it("retains JSON console routing through process finalization", async () => {
@@ -26,7 +25,6 @@ describe("entry run-main boundary", () => {
       humanOutput: message,
       machineOutput: message,
     });
-    enableConsoleCapture();
     const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
     process.exitCode = undefined;
 
diff --git a/src/mcp/codex-supervision-tools-serve.test.ts b/src/mcp/codex-supervision-tools-serve.test.ts
index bf503ea6c9b9..69c97a7a05e5 100644
--- a/src/mcp/codex-supervision-tools-serve.test.ts
+++ b/src/mcp/codex-supervision-tools-serve.test.ts
@@ -1,9 +1,8 @@
 // Codex supervision MCP tests cover the retired Supervisor command bridge.
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { AnyAgentTool } from "../agents/tools/common.js";
-import { loggingState } from "../logging/state.js";
 import {
   createCodexSupervisionToolsMcpServer,
   serveCodexSupervisionToolsMcp,
@@ -49,7 +48,6 @@ const TOOL_NAMES = [
   "codex_session_send",
   "codex_session_interrupt",
 ] as const;
-let originalForceConsoleToStderr = false;
 
 function createTools(): AnyAgentTool[] {
   return TOOL_NAMES.map(
@@ -66,7 +64,6 @@ function createTools(): AnyAgentTool[] {
 
 describe("createCodexSupervisionToolsMcpServer", () => {
   beforeEach(() => {
-    originalForceConsoleToStderr = loggingState.forceConsoleToStderr;
     ensureStandalonePluginToolRegistryLoadedMock.mockClear();
     resolvePluginToolsMock.mockReset();
     resolvePluginToolsMock.mockReturnValue([]);
@@ -74,10 +71,6 @@ describe("createCodexSupervisionToolsMcpServer", () => {
     disposeRegisteredAgentHarnessesMock.mockClear();
   });
 
-  afterEach(() => {
-    loggingState.forceConsoleToStderr = originalForceConsoleToStderr;
-  });
-
   it("fails closed when the external Codex plugin tools are unavailable", () => {
     expect(() =>
       createCodexSupervisionToolsMcpServer({
diff --git a/test/non-isolated-runner.test.ts b/test/non-isolated-runner.test.ts
index 4c267cffc01c..98e2959a1d90 100644
--- a/test/non-isolated-runner.test.ts
+++ b/test/non-isolated-runner.test.ts
@@ -48,6 +48,8 @@ function fixtureFiles(): Record<string, string> {
     path.join(repoRoot, "src", "infra", "agent-run-registry.ts"),
   );
   const agentEventsPath = JSON.stringify(path.join(repoRoot, "src", "infra", "agent-events.ts"));
+  const loggingConsolePath = JSON.stringify(path.join(repoRoot, "src", "logging", "console.ts"));
+  const loggingStatePath = JSON.stringify(path.join(repoRoot, "src", "logging", "state.ts"));
 
   return {
     "01-dep.ts": 'export function flavor(): string {\n  return "real";\n}\n',
@@ -161,6 +163,39 @@ function fixtureFiles(): Record<string, string> {
       "});",
       "",
     ].join("\n"),
+    "06-a-console-routing.test.ts": [
+      `import { enableConsoleCapture, routeLogsToStderr } from ${loggingConsolePath};`,
+      `import { loggingState } from ${loggingStatePath};`,
+      'import { expect, it } from "vitest";',
+      'it("latches console capture and stderr routing", () => {',
+      "  const native = console.error;",
+      "  routeLogsToStderr();",
+      "  enableConsoleCapture();",
+      "  expect(loggingState.forceConsoleToStderr).toBe(true);",
+      "  expect(loggingState.consolePatched).toBe(true);",
+      "  expect(console.error).not.toBe(native);",
+      "});",
+      "",
+    ].join("\n"),
+    // Production never unwinds those latches: a stdio MCP server or a `--json`
+    // one-shot owns the console until the process exits. The next file must still
+    // see its own console.error spy, not the previous file's stderr forwarder.
+    "06-b-console-routing.test.ts": [
+      `import { enableConsoleCapture } from ${loggingConsolePath};`,
+      `import { loggingState } from ${loggingStatePath};`,
+      'import { expect, it, vi } from "vitest";',
+      'it("starts from unrouted, unpatched console state", () => {',
+      "  expect(loggingState.forceConsoleToStderr).toBe(false);",
+      "  expect(loggingState.consolePatched).toBe(false);",
+      "  expect(loggingState.rawConsole).toBeNull();",
+      '  const spy = vi.spyOn(console, "error").mockImplementation(() => {});',
+      "  enableConsoleCapture();",
+      '  console.error("routed line");',
+      '  expect(spy.mock.calls).toEqual([["routed line"]]);',
+      "  spy.mockRestore();",
+      "});",
+      "",
+    ].join("\n"),
   };
 }
 
@@ -216,7 +251,7 @@ it("cleans every shared runner surface between files", async () => {
     // The collection failure is intentional. Every behavior test after it must
     // pass; any leaked surface turns the summary into a second failure.
     expect(output).toContain("synthetic collect failure");
-    expect(output).toContain("1 failed | 9 passed");
+    expect(output).toContain("1 failed | 11 passed");
     expect(output).not.toContain("first-file");
   } finally {
     await fs.rm(root, { recursive: true, force: true });
diff --git a/test/non-isolated-runner.ts b/test/non-isolated-runner.ts
index 6cc730d35623..024f64969799 100644
--- a/test/non-isolated-runner.ts
+++ b/test/non-isolated-runner.ts
@@ -2,6 +2,7 @@
 import path from "node:path";
 import { TestRunner, type RunnerTask, type RunnerTestFile, vi } from "vitest";
 import { resetAgentEventsForTest } from "../src/infra/agent-events.js";
+import { loggingState } from "../src/logging/state.js";
 import { clearNamedPluginRuntimeStoresForTest } from "../src/plugin-sdk/runtime-store-registry.js";
 import {
   type CustomElementTracking,
@@ -40,6 +41,17 @@ const DIAGNOSTIC_EVENT_LISTENER_PRESENCE = Symbol.for(
 const SESSION_SUSPENSION_TEST_API = Symbol.for("openclaw.sessionSuspensionTestApi");
 // Shared-worker scoped: the registry lives on the worker global, not in the module graph.
 const CUSTOM_ELEMENT_TRACKING = Symbol.for("openclaw.nonIsolatedCustomElementTracking");
+const nativeConsoleMethods = {
+  log: console.log,
+  info: console.info,
+  warn: console.warn,
+  error: console.error,
+  debug: console.debug,
+  trace: console.trace,
+};
+// loggingState is keyed off globalThis precisely so it survives module reloads,
+// so vi.resetModules() below cannot undo what a file latched into it.
+const baselineLoggingState = { ...loggingState };
 const nativeTimerGlobals = {
   setTimeout: globalThis.setTimeout,
   clearTimeout: globalThis.clearTimeout,
@@ -146,6 +158,19 @@ function restoreNativeTimerGlobals(): void {
   Object.assign(globalThis, nativeTimerGlobals);
 }
 
+// enableConsoleCapture() swaps every console method for a forwarder and latches
+// routing that production only unwinds at process exit (stdio MCP servers, `--json`
+// one-shot commands), so a shared worker carries both into the next file. That
+// forwarder writes to process.stderr once forceConsoleToStderr is latched, and the
+// next file's console spy then records nothing.
+function restoreConsoleRoutingState(): void {
+  Object.assign(console, nativeConsoleMethods);
+  // The EPIPE handlers really are attached to the worker's stdout/stderr; resetting
+  // this flag would let the next enableConsoleCapture() stack a second pair.
+  const { streamErrorHandlersInstalled } = loggingState;
+  Object.assign(loggingState, baselineLoggingState, { streamErrorHandlersInstalled });
+}
+
 function restoreMocksThenRealTimers(): void {
   // A spy created while fake timers are active captures the fake timer as its
   // "original" implementation. Restore spies first, then swap timers back.
@@ -435,6 +460,7 @@ export default class OpenClawNonIsolatedRunner extends TestRunner {
     // not carry file-scoped timers, stubs, spies, or stale module state
     // forward into the next file.
     restoreMocksThenRealTimers();
+    restoreConsoleRoutingState();
     vi.unstubAllGlobals();
     const testHome = getSharedTestHome();
     vi.unstubAllEnvs();

From 9903e404ef9ffb2212f8822054001c3d972f696f Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 15:06:17 -0700
Subject: [PATCH 107/124] feat(ui): add live CPU/memory/delay sparkline graphs
 to the system busyness overlay (#127650)

* feat(ui): add cpu/memory graphs to system busyness overlay

* refactor(ui): redesign busyness overlay vitals as sparkline stat tiles

Merge the duplicated sparkline row and numeric tile grid into three vital
tiles (CPU, memory, event-loop delay) with gradient area charts, a live
pulse dot, pointer scrubbing with value+age readout, and a danger tint
driven by the gateway's own event-loop degradation reasons. Memory
auto-ranges its baseline so RSS trends stay visible.
---
 docs/web/control-ui.md                        |   2 +-
 scripts/control-ui-mock-dev.ts                |   7 +-
 .../health.owner-routing.test.ts              |   9 +
 src/gateway/server-methods/health.ts          |   6 +
 .../server-methods/server-methods.test.ts     |   4 +-
 src/status/types.ts                           |   5 +
 ui/src/i18n/locales/en.ts                     |   8 +-
 ui/src/pages/debug/debug-overlay-sections.ts  | 140 ++++++++++----
 ui/src/pages/debug/debug-overlay.ts           |  15 +-
 ui/src/pages/debug/sparkline-tile.ts          | 171 ++++++++++++++++++
 ui/src/pages/debug/view.test.ts               | 114 +++++++++++-
 ui/src/styles/debug.css                       | 121 +++++++++++--
 12 files changed, 541 insertions(+), 61 deletions(-)
 create mode 100644 ui/src/pages/debug/sparkline-tile.ts

diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index 9090fb70d11f..30a61a7991e1 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -331,7 +331,7 @@ select it to open the owning Approvals page.
 
   </Accordion>
   <Accordion title="Debug, logs, update">
-    - Debug: status/health/models snapshots, event log, and manual RPC calls (`status`, `health`, `models.list`).
+    - Debug: status/health/models snapshots, event log, manual RPC calls, and a System busyness overlay with live CPU, memory, and event-loop delay graphs (`status`, `health`, `models.list`).
     - The event log includes Control UI refresh/RPC timings, slow chat/config render timings, and browser responsiveness entries for long animation frames or long tasks when the browser exposes those PerformanceObserver entry types.
     - Logs: live tail of gateway file logs with filter/export (`logs.tail`).
     - Update: run a package/git update plus restart (`update.run`) with a restart report, then poll `update.status` after reconnect to verify the running gateway version.
diff --git a/scripts/control-ui-mock-dev.ts b/scripts/control-ui-mock-dev.ts
index 844d3a2f1c93..80dc4d593b02 100644
--- a/scripts/control-ui-mock-dev.ts
+++ b/scripts/control-ui-mock-dev.ts
@@ -2623,7 +2623,12 @@ async function createChatPickerScenario(
         },
       },
       status: {
-        eventLoop: { utilization: 0.42, delayP99Ms: 12, delayMaxMs: 87 },
+        eventLoop: { utilization: 0.42, cpuCoreRatio: 0.24, delayP99Ms: 12, delayMaxMs: 87 },
+        processMemory: {
+          rssBytes: 432 * 1_048_576,
+          heapUsedBytes: 210 * 1_048_576,
+          heapTotalBytes: 280 * 1_048_576,
+        },
         uptimeMs: 5_412_000,
       },
       "last-heartbeat": { ts: baseTime },
diff --git a/src/gateway/server-methods/health.owner-routing.test.ts b/src/gateway/server-methods/health.owner-routing.test.ts
index 38eff260af82..eea35dd98ef4 100644
--- a/src/gateway/server-methods/health.owner-routing.test.ts
+++ b/src/gateway/server-methods/health.owner-routing.test.ts
@@ -40,6 +40,15 @@ describe("Gateway status owner routing", () => {
 
       expect(respond).toHaveBeenCalledTimes(1);
       expect(respond.mock.calls[0]?.[0]).toBe(true);
+      expect(respond.mock.calls[0]?.[1]).toEqual(
+        expect.objectContaining({
+          processMemory: {
+            rssBytes: expect.any(Number),
+            heapUsedBytes: expect.any(Number),
+            heapTotalBytes: expect.any(Number),
+          },
+        }),
+      );
       expect(respond.mock.calls[0]?.[2]).toBeUndefined();
       expect(resolveRequestedSessionAgentId(config, "main")).toMatchObject({ ok: false });
       expect(resolveRequestedSessionAgentId(config, "agent:molty:main")).toEqual({
diff --git a/src/gateway/server-methods/health.ts b/src/gateway/server-methods/health.ts
index cbad1592f59a..ee555ef77b0f 100644
--- a/src/gateway/server-methods/health.ts
+++ b/src/gateway/server-methods/health.ts
@@ -184,6 +184,12 @@ export const healthHandlers: GatewayRequestHandlers = {
     if (context.getEventLoopHealth) {
       status.eventLoop = context.getEventLoopHealth();
     }
+    const memory = process.memoryUsage();
+    status.processMemory = {
+      rssBytes: memory.rss,
+      heapUsedBytes: memory.heapUsed,
+      heapTotalBytes: memory.heapTotal,
+    };
     respond(true, status, undefined);
   },
 };
diff --git a/src/gateway/server-methods/server-methods.test.ts b/src/gateway/server-methods/server-methods.test.ts
index 47fecd477c35..be721368b98c 100644
--- a/src/gateway/server-methods/server-methods.test.ts
+++ b/src/gateway/server-methods/server-methods.test.ts
@@ -4375,7 +4375,7 @@ describe("gateway healthHandlers.status scope handling", () => {
         includeSensitive,
         includeChannelSummary: true,
       });
-      expect(respond).toHaveBeenCalledWith(true, { ok: true }, undefined);
+      expect(respond).toHaveBeenCalledWith(true, expect.objectContaining({ ok: true }), undefined);
     },
   );
 
@@ -4398,7 +4398,7 @@ describe("gateway healthHandlers.status scope handling", () => {
       includeSensitive: false,
       includeChannelSummary: false,
     });
-    expect(respond).toHaveBeenCalledWith(true, { ok: true }, undefined);
+    expect(respond).toHaveBeenCalledWith(true, expect.objectContaining({ ok: true }), undefined);
   });
 });
 
diff --git a/src/status/types.ts b/src/status/types.ts
index d68988005da2..458af0d65502 100644
--- a/src/status/types.ts
+++ b/src/status/types.ts
@@ -56,6 +56,11 @@ export type StatusSummary = {
   runtimeVersion?: string | null;
   hostDesktop?: import("../gateway/desktop/host-source.js").HostDesktopStatus;
   eventLoop?: import("../gateway/server/event-loop-health.js").GatewayEventLoopHealth;
+  processMemory?: {
+    rssBytes: number;
+    heapUsedBytes: number;
+    heapTotalBytes: number;
+  };
   linkChannel?: {
     id: ChannelId;
     label: string;
diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts
index 019940ecdc28..e63dea6f005d 100644
--- a/ui/src/i18n/locales/en.ts
+++ b/ui/src/i18n/locales/en.ts
@@ -1439,9 +1439,13 @@ export const en: TranslationMap = {
       status: "Event loop / status",
       activeRuns: "Active runs",
       events: "Events",
-      utilization: "Utilization",
+      cpu: "CPU",
+      memory: "Memory",
+      memoryMb: "{value} MB",
+      loopShort: "loop {value}",
+      heapShort: "heap {value}",
+      maxShort: "max {value}",
       delayP99: "Delay p99",
-      delayMax: "Delay max",
       uptime: "Uptime",
       activeRunsCount: "{count} active",
       noActiveRuns: "No active runs.",
diff --git a/ui/src/pages/debug/debug-overlay-sections.ts b/ui/src/pages/debug/debug-overlay-sections.ts
index 1293f411614a..7c69cc7fe47b 100644
--- a/ui/src/pages/debug/debug-overlay-sections.ts
+++ b/ui/src/pages/debug/debug-overlay-sections.ts
@@ -1,5 +1,5 @@
 import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
-import { html, type TemplateResult } from "lit";
+import { html, nothing, type TemplateResult } from "lit";
 import type { GatewayBrowserClient } from "../../api/gateway.ts";
 import type { ApplicationGateway } from "../../app/gateway.ts";
 import { t } from "../../i18n/index.ts";
@@ -13,6 +13,8 @@ import {
   type CommandLaneDiagnostics,
 } from "../../lib/gateway-diagnostics.ts";
 import { renderCommandLaneRows } from "./lane-table.ts";
+import "./sparkline-tile.ts";
+import type { SparklineSample } from "./sparkline-tile.ts";
 
 type DebugOverlaySectionContext = {
   client: GatewayBrowserClient;
@@ -23,7 +25,7 @@ type TypedDebugOverlaySectionDescriptor<T> = {
   id: string;
   titleKey: string;
   load: (context: DebugOverlaySectionContext, signal: AbortSignal) => Promise<T>;
-  render: (value: T) => TemplateResult;
+  render: (value: T, statusHistory: readonly DebugOverlayStatusSample[]) => TemplateResult;
 };
 
 export type DebugOverlaySectionDescriptor = TypedDebugOverlaySectionDescriptor<unknown>;
@@ -33,24 +35,36 @@ function defineDebugOverlaySection<T>(
 ): DebugOverlaySectionDescriptor {
   return {
     ...descriptor,
-    render: (value) => {
+    render: (value, statusHistory) => {
       // SAFETY: This closure keeps each descriptor's load result paired with its own renderer.
-      return descriptor.render(value as T);
+      return descriptor.render(value as T, statusHistory);
     },
   };
 }
 
 type EventLoopSnapshot = {
   utilization?: number;
+  cpuCoreRatio?: number;
   delayP99Ms?: number;
   delayMaxMs?: number;
+  reasons?: string[];
 };
 
-type StatusSectionValue = {
+export type DebugOverlayStatusSnapshot = {
   eventLoop?: EventLoopSnapshot;
+  processMemory?: {
+    rssBytes: number;
+    heapUsedBytes: number;
+    heapTotalBytes: number;
+  };
   uptimeMs?: number;
 };
 
+export type DebugOverlayStatusSample = {
+  at: number;
+  status: DebugOverlayStatusSnapshot;
+};
+
 type ActiveSession = {
   key?: string;
   sessionId?: string;
@@ -76,41 +90,86 @@ function renderLanes(diagnostics: CommandLaneDiagnostics): TemplateResult {
   `;
 }
 
-function renderStatus(status: StatusSectionValue): TemplateResult {
+function collectSamples(
+  history: readonly DebugOverlayStatusSample[],
+  read: (status: DebugOverlayStatusSnapshot) => number | undefined,
+): SparklineSample[] {
+  const samples: SparklineSample[] = [];
+  for (const entry of history) {
+    const value = read(entry.status);
+    if (typeof value === "number" && Number.isFinite(value)) {
+      samples.push({ value, at: entry.at });
+    }
+  }
+  return samples;
+}
+
+function formatPercent(value: number): string {
+  return `${Math.round(value * 100)}%`;
+}
+
+function formatMegabytes(bytes: number): string {
+  return t("debug.overlay.memoryMb", { value: String(Math.round(bytes / 1_048_576)) });
+}
+
+function formatDelayMs(value: number): string {
+  return formatDurationCompact(value) ?? t("common.na");
+}
+
+function renderStatus(
+  status: DebugOverlayStatusSnapshot,
+  history: readonly DebugOverlayStatusSample[],
+): TemplateResult {
   const eventLoop = status.eventLoop;
-  const utilization =
+  const reasons = eventLoop?.reasons ?? [];
+  const cpuDegraded = reasons.includes("cpu") || reasons.includes("event_loop_utilization");
+  const delayDegraded = reasons.includes("event_loop_delay");
+  const loopSub =
     typeof eventLoop?.utilization === "number"
-      ? `${Math.round(eventLoop.utilization * 100)}%`
-      : t("common.na");
-  const delay =
-    typeof eventLoop?.delayP99Ms === "number"
-      ? formatDurationCompact(eventLoop.delayP99Ms)
-      : t("common.na");
-  const maxDelay =
+      ? t("debug.overlay.loopShort", { value: formatPercent(eventLoop.utilization) })
+      : "";
+  const heapSub =
+    typeof status.processMemory?.heapUsedBytes === "number"
+      ? t("debug.overlay.heapShort", { value: formatMegabytes(status.processMemory.heapUsedBytes) })
+      : "";
+  const maxSub =
     typeof eventLoop?.delayMaxMs === "number"
-      ? formatDurationCompact(eventLoop.delayMaxMs)
-      : t("common.na");
+      ? t("debug.overlay.maxShort", { value: formatDelayMs(eventLoop.delayMaxMs) })
+      : "";
   return html`
-    <dl class="debug-overlay__metrics">
-      <div>
-        <dt>${t("debug.overlay.utilization")}</dt>
-        <dd class="mono">${utilization}</dd>
-      </div>
-      <div>
-        <dt>${t("debug.overlay.delayP99")}</dt>
-        <dd class="mono">${delay}</dd>
-      </div>
-      <div>
-        <dt>${t("debug.overlay.delayMax")}</dt>
-        <dd class="mono">${maxDelay}</dd>
-      </div>
-      ${typeof status.uptimeMs === "number"
-        ? html`<div>
-            <dt>${t("debug.overlay.uptime")}</dt>
-            <dd class="mono">${formatDurationHuman(status.uptimeMs)}</dd>
-          </div>`
-        : ""}
-    </dl>
+    <div class="debug-overlay__vitals">
+      <openclaw-debug-sparkline
+        class="debug-overlay__vital debug-overlay__vital--cpu"
+        data-degraded=${cpuDegraded ? "" : nothing}
+        .label=${t("debug.overlay.cpu")}
+        .sub=${loopSub}
+        .samples=${collectSamples(history, (sample) => sample.eventLoop?.cpuCoreRatio)}
+        .format=${formatPercent}
+        .floorMax=${1}
+      ></openclaw-debug-sparkline>
+      <openclaw-debug-sparkline
+        class="debug-overlay__vital debug-overlay__vital--memory"
+        .label=${t("debug.overlay.memory")}
+        .sub=${heapSub}
+        .samples=${collectSamples(history, (sample) => sample.processMemory?.rssBytes)}
+        .format=${formatMegabytes}
+        autorange
+      ></openclaw-debug-sparkline>
+      <openclaw-debug-sparkline
+        class="debug-overlay__vital debug-overlay__vital--delay"
+        data-degraded=${delayDegraded ? "" : nothing}
+        .label=${t("debug.overlay.delayP99")}
+        .sub=${maxSub}
+        .samples=${collectSamples(history, (sample) => sample.eventLoop?.delayP99Ms)}
+        .format=${formatDelayMs}
+        .floorMax=${20}
+      ></openclaw-debug-sparkline>
+    </div>
+    ${typeof status.uptimeMs === "number"
+      ? html`<div class="debug-overlay__vitals-footer mono">
+          ${t("debug.overlay.uptime")} ${formatDurationHuman(status.uptimeMs)}
+        </div>`
+      : nothing}
   `;
 }
 
@@ -156,11 +215,16 @@ export const DEBUG_OVERLAY_SECTIONS: readonly DebugOverlaySectionDescriptor[] =
     id: "status",
     titleKey: "debug.overlay.status",
     load: async (context, signal) => {
-      const value = await context.client.request<StatusSectionValue>("status", {}, { signal });
+      const value = await context.client.request<DebugOverlayStatusSnapshot>(
+        "status",
+        {},
+        { signal },
+      );
       return {
         eventLoop: value.eventLoop,
+        processMemory: value.processMemory,
         ...(typeof value.uptimeMs === "number" ? { uptimeMs: value.uptimeMs } : {}),
-      } satisfies StatusSectionValue;
+      } satisfies DebugOverlayStatusSnapshot;
     },
     render: renderStatus,
   }),
diff --git a/ui/src/pages/debug/debug-overlay.ts b/ui/src/pages/debug/debug-overlay.ts
index e116ed6b82bf..f0983126622d 100644
--- a/ui/src/pages/debug/debug-overlay.ts
+++ b/ui/src/pages/debug/debug-overlay.ts
@@ -9,9 +9,12 @@ import "../../styles/debug.css";
 import {
   DEBUG_OVERLAY_SECTIONS,
   type DebugOverlaySectionDescriptor,
+  type DebugOverlayStatusSample,
+  type DebugOverlayStatusSnapshot,
 } from "./debug-overlay-sections.ts";
 
 const DEBUG_OVERLAY_POLL_INTERVAL_MS = 2000;
+const DEBUG_OVERLAY_HISTORY_LIMIT = 90;
 
 type SectionState =
   | { status: "loading" }
@@ -28,6 +31,7 @@ export class DebugOverlay extends OpenClawLightDomElement {
   private requestController: AbortController | null = null;
   private requestActive = false;
   private requestGeneration = 0;
+  private statusHistory: DebugOverlayStatusSample[] = [];
   private eventLogSource: ApplicationContext["gateway"] | null = null;
   private unsubscribeEventLog: (() => void) | null = null;
   private readonly polling = new PollController(
@@ -54,6 +58,7 @@ export class DebugOverlay extends OpenClawLightDomElement {
       return;
     }
     this.open = true;
+    this.statusHistory = [];
     document.addEventListener("keydown", this.handleKeydown, true);
     this.syncEventLogSubscription();
     this.sections = new Map(
@@ -134,6 +139,14 @@ export class DebugOverlay extends OpenClawLightDomElement {
     if (!this.open || generation !== this.requestGeneration) {
       return;
     }
+    if (id === "status" && state.status === "ready") {
+      // SAFETY: The status descriptor owns this section id and always returns a status snapshot.
+      const snapshot = state.value as DebugOverlayStatusSnapshot;
+      this.statusHistory = [
+        ...this.statusHistory.slice(-(DEBUG_OVERLAY_HISTORY_LIMIT - 1)),
+        { at: Date.now(), status: snapshot },
+      ];
+    }
     const next = new Map(this.sections);
     next.set(id, state);
     this.sections = next;
@@ -148,7 +161,7 @@ export class DebugOverlay extends OpenClawLightDomElement {
           ? html`<div class="debug-overlay__empty">${t("common.loading")}</div>`
           : state.status === "unavailable"
             ? html`<div class="debug-overlay__empty">${t("debug.overlay.unavailable")}</div>`
-            : section.render(state.value)}
+            : section.render(state.value, this.statusHistory)}
       </section>
     `;
   }
diff --git a/ui/src/pages/debug/sparkline-tile.ts b/ui/src/pages/debug/sparkline-tile.ts
new file mode 100644
index 000000000000..e28b9e968771
--- /dev/null
+++ b/ui/src/pages/debug/sparkline-tile.ts
@@ -0,0 +1,171 @@
+import { html, nothing, svg } from "lit";
+import { property, state as litState } from "lit/decorators.js";
+import { formatDurationCompact } from "../../lib/format.ts";
+import { OpenClawLightDomElement } from "../../lit/openclaw-element.ts";
+
+export type SparklineSample = { value: number; at: number };
+
+// Chart geometry in viewBox units; the svg stretches (preserveAspectRatio="none"),
+// so hover/now markers are positioned with percentages in HTML instead.
+const CHART_WIDTH = 100;
+const CHART_HEIGHT = 40;
+const CHART_TOP_PAD = 4;
+
+// Gradient defs need document-unique ids: the overlay renders one tile per vital
+// into the light DOM, so a shared static id would collide across instances.
+let gradientCounter = 0;
+
+function nextGradientId(): string {
+  gradientCounter += 1;
+  return `debug-vital-gradient-${gradientCounter}`;
+}
+
+/** Stat tile with an embedded area sparkline and pointer scrubbing. */
+class DebugSparklineTile extends OpenClawLightDomElement {
+  @property() label = "";
+  @property() sub = "";
+  @property({ attribute: false }) samples: readonly SparklineSample[] = [];
+  @property({ attribute: false }) format: (value: number) => string = String;
+  /** Lower bound for the y-axis top, so quiet metrics keep a calm scale. */
+  @property({ attribute: false }) floorMax = 0;
+  /** Auto-range the baseline near the series minimum instead of zero, so
+   * large-but-steady metrics (RSS) still show their trend shape. */
+  @property({ type: Boolean }) autorange = false;
+
+  @litState() private hoverIndex: number | null = null;
+
+  private readonly gradientId = nextGradientId();
+
+  private get yRange(): { min: number; span: number } {
+    let max = this.floorMax;
+    let min = Number.POSITIVE_INFINITY;
+    for (const sample of this.samples) {
+      if (sample.value > max) {
+        max = sample.value;
+      }
+      if (sample.value < min) {
+        min = sample.value;
+      }
+    }
+    if (!Number.isFinite(min)) {
+      min = 0;
+    }
+    if (!this.autorange) {
+      return { min: 0, span: max > 0 ? max : 1 };
+    }
+    // Sit the baseline a bit below the observed minimum so the shape stays a
+    // trend line, not a wall, while never faking a drop to zero.
+    const spread = Math.max(max - min, max * 0.02, 1e-9);
+    const base = Math.max(min - spread * 0.5, 0);
+    return { min: base, span: Math.max(max - base, 1e-9) };
+  }
+
+  private toY(value: number): number {
+    const { min, span } = this.yRange;
+    const usable = CHART_HEIGHT - CHART_TOP_PAD;
+    const ratio = Math.min(Math.max((value - min) / span, 0), 1);
+    return CHART_HEIGHT - ratio * usable;
+  }
+
+  private readonly handlePointerMove = (event: PointerEvent): void => {
+    if (this.samples.length < 2) {
+      return;
+    }
+    const target = event.currentTarget;
+    if (!(target instanceof HTMLElement)) {
+      return;
+    }
+    const ratio = event.offsetX / Math.max(target.clientWidth, 1);
+    const index = Math.round(ratio * (this.samples.length - 1));
+    this.hoverIndex = Math.min(Math.max(index, 0), this.samples.length - 1);
+  };
+
+  private readonly handlePointerLeave = (): void => {
+    this.hoverIndex = null;
+  };
+
+  private renderChart() {
+    const samples = this.samples;
+    if (samples.length < 2) {
+      return nothing;
+    }
+    const step = CHART_WIDTH / (samples.length - 1);
+    const points = samples
+      .map((sample, index) => `${index * step},${this.toY(sample.value)}`)
+      .join(" ");
+    const last = samples.at(-1);
+    if (!last) {
+      return nothing;
+    }
+    const lastY = this.toY(last.value);
+    const hover = this.hoverIndex !== null ? samples[this.hoverIndex] : undefined;
+    const hoverLeft = this.hoverIndex !== null ? (this.hoverIndex / (samples.length - 1)) * 100 : 0;
+    return html`
+      <div
+        class="debug-vital__chart"
+        @pointermove=${this.handlePointerMove}
+        @pointerleave=${this.handlePointerLeave}
+      >
+        <svg
+          viewBox="0 0 ${CHART_WIDTH} ${CHART_HEIGHT}"
+          preserveAspectRatio="none"
+          aria-hidden="true"
+        >
+          ${svg`
+            <defs>
+              <linearGradient id=${this.gradientId} x1="0" y1="0" x2="0" y2="1">
+                <stop offset="0" stop-color="currentColor" stop-opacity="0.28"></stop>
+                <stop offset="1" stop-color="currentColor" stop-opacity="0.02"></stop>
+              </linearGradient>
+            </defs>
+            <polygon
+              points="0,${CHART_HEIGHT} ${points} ${CHART_WIDTH},${CHART_HEIGHT}"
+              fill="url(#${this.gradientId})"
+            ></polygon>
+            <polyline points=${points}></polyline>
+          `}
+        </svg>
+        ${hover
+          ? html`
+              <div class="debug-vital__hairline" style="left: ${hoverLeft}%"></div>
+              <div
+                class="debug-vital__dot debug-vital__dot--hover"
+                style="left: ${hoverLeft}%; top: ${(this.toY(hover.value) / CHART_HEIGHT) * 100}%"
+              ></div>
+            `
+          : html`
+              <div
+                class="debug-vital__dot debug-vital__dot--now"
+                style="left: calc(100% - 3px); top: ${(lastY / CHART_HEIGHT) * 100}%"
+              ></div>
+            `}
+      </div>
+    `;
+  }
+
+  override render() {
+    const samples = this.samples;
+    const current = samples.at(-1);
+    const hover = this.hoverIndex !== null ? samples[this.hoverIndex] : null;
+    const shown = hover ?? current;
+    const age =
+      hover && current && current.at > hover.at
+        ? formatDurationCompact(current.at - hover.at)
+        : null;
+    return html`
+      <div class="debug-vital__head">
+        <span class="debug-vital__label">${this.label}</span>
+        ${this.sub ? html`<span class="debug-vital__sub mono">${this.sub}</span>` : nothing}
+      </div>
+      <div class="debug-vital__value mono">
+        ${shown ? this.format(shown.value) : "–"}
+        ${age ? html`<span class="debug-vital__age">−${age}</span>` : nothing}
+      </div>
+      ${this.renderChart()}
+    `;
+  }
+}
+
+if (!customElements.get("openclaw-debug-sparkline")) {
+  customElements.define("openclaw-debug-sparkline", DebugSparklineTile);
+}
diff --git a/ui/src/pages/debug/view.test.ts b/ui/src/pages/debug/view.test.ts
index bb237a3e757e..d668d6f13015 100644
--- a/ui/src/pages/debug/view.test.ts
+++ b/ui/src/pages/debug/view.test.ts
@@ -1,10 +1,11 @@
 // Control UI tests cover debug behavior.
-import { render } from "lit";
+import { render, type LitElement } from "lit";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { GatewayBrowserClient } from "../../api/gateway.ts";
 import type { ApplicationContext, ApplicationGatewaySnapshot } from "../../app/context.ts";
 import { i18n } from "../../i18n/index.ts";
 import { createStorageMock } from "../../test-helpers/storage.ts";
+import "./debug-overlay.ts";
 import "./debug-page.ts";
 import { renderDebug } from "./view.ts";
 
@@ -34,6 +35,12 @@ type TestDebugPage = HTMLElement & {
   loadDiagnostics: () => Promise<void>;
 };
 
+type TestDebugOverlay = HTMLElement & {
+  readonly updateComplete: Promise<boolean>;
+  context: ApplicationContext;
+  toggle: () => void;
+};
+
 function deferred<T>() {
   let resolve!: (value: T) => void;
   let reject!: (reason?: unknown) => void;
@@ -44,9 +51,9 @@ function deferred<T>() {
   return { promise, resolve, reject };
 }
 
-async function mountDebugPage(
+function createDebugApplicationContext(
   request: (method: string) => Promise<unknown>,
-): Promise<TestDebugPage> {
+): ApplicationContext {
   const client = { request } as unknown as GatewayBrowserClient;
   const gateway = {
     snapshot: { phase: "connected", client } as ApplicationGatewaySnapshot,
@@ -58,8 +65,14 @@ async function mountDebugPage(
     state: { selectedId: "main" },
     subscribe: () => () => undefined,
   } as unknown as ApplicationContext["agentSelection"];
+  return { agentSelection, basePath: "", gateway } as ApplicationContext;
+}
+
+async function mountDebugPage(
+  request: (method: string) => Promise<unknown>,
+): Promise<TestDebugPage> {
   const page = document.createElement("openclaw-debug-page") as TestDebugPage;
-  page.context = { agentSelection, basePath: "", gateway } as ApplicationContext;
+  page.context = createDebugApplicationContext(request);
   document.body.append(page);
   await vi.waitFor(() => expect(page.debugStatus).not.toBeNull());
   return page;
@@ -336,3 +349,96 @@ describe("DebugPage", () => {
     expect(page.debugCallError).toContain("manual request failed");
   });
 });
+
+describe("DebugOverlay", () => {
+  it("graphs bounded status samples without clamping CPU and resets history on reopen", async () => {
+    vi.useFakeTimers();
+    let sampleCount = 0;
+    const request = vi.fn(async (method: string) => {
+      if (method === "status") {
+        sampleCount += 1;
+        return {
+          eventLoop: {
+            utilization: 0.42,
+            cpuCoreRatio: 1 + sampleCount / 10,
+            delayP99Ms: 10 + sampleCount,
+            delayMaxMs: 87,
+          },
+          processMemory: {
+            rssBytes: (400 + sampleCount) * 1_048_576,
+            heapUsedBytes: 100 * 1_048_576,
+            heapTotalBytes: 200 * 1_048_576,
+          },
+        };
+      }
+      if (method === "sessions.list") {
+        return { sessions: [] };
+      }
+      return diagnosticResponse(method);
+    });
+    const overlay = document.createElement("openclaw-debug-overlay") as TestDebugOverlay;
+    overlay.context = createDebugApplicationContext(request);
+    document.body.append(overlay);
+
+    try {
+      overlay.toggle();
+      await vi.advanceTimersByTimeAsync(0);
+      await overlay.updateComplete;
+
+      const vitalUpdated = async () => {
+        await overlay.updateComplete;
+        for (const tile of overlay.querySelectorAll("openclaw-debug-sparkline")) {
+          await (tile as LitElement).updateComplete;
+        }
+      };
+      await vitalUpdated();
+
+      // One sample: tiles show current values, charts wait for a second point.
+      expect(overlay.querySelectorAll(".debug-overlay__vital")).toHaveLength(3);
+      expect(normalizedText(overlay.querySelector(".debug-overlay__vital--cpu"))).toContain(
+        "loop 42%",
+      );
+      expect(overlay.querySelector(".debug-vital__chart")).toBeNull();
+
+      await vi.advanceTimersByTimeAsync(2_000);
+      await vitalUpdated();
+
+      expect(normalizedText(overlay.querySelector(".debug-overlay__vital--cpu"))).toContain("120%");
+      expect(normalizedText(overlay.querySelector(".debug-overlay__vital--memory"))).toContain(
+        "402 MB",
+      );
+      expect(normalizedText(overlay.querySelector(".debug-overlay__vital--memory"))).toContain(
+        "heap 100 MB",
+      );
+      expect(normalizedText(overlay.querySelector(".debug-overlay__vital--delay"))).toContain(
+        "12ms",
+      );
+      expect(normalizedText(overlay.querySelector(".debug-overlay__vital--delay"))).toContain(
+        "max 87ms",
+      );
+      expect(overlay.querySelectorAll(".debug-vital__chart")).toHaveLength(3);
+      // Healthy event loop: no tile carries the degraded tint.
+      expect(overlay.querySelector(".debug-overlay__vital[data-degraded]")).toBeNull();
+
+      await vi.advanceTimersByTimeAsync(180_000);
+      await vitalUpdated();
+
+      const points = overlay
+        .querySelector(".debug-overlay__vital--cpu polyline")
+        ?.getAttribute("points")
+        ?.split(" ");
+      expect(points).toHaveLength(90);
+
+      overlay.toggle();
+      overlay.toggle();
+      await vi.advanceTimersByTimeAsync(0);
+      await vitalUpdated();
+
+      expect(overlay.querySelectorAll(".debug-overlay__vital")).toHaveLength(3);
+      expect(overlay.querySelector(".debug-vital__chart")).toBeNull();
+    } finally {
+      overlay.remove();
+      vi.useRealTimers();
+    }
+  });
+});
diff --git a/ui/src/styles/debug.css b/ui/src/styles/debug.css
index 37a4244763c4..60d6f2a1331b 100644
--- a/ui/src/styles/debug.css
+++ b/ui/src/styles/debug.css
@@ -128,32 +128,129 @@ openclaw-debug-overlay {
   padding: 6px 8px;
 }
 
-.debug-overlay__metrics {
+.debug-overlay__vitals {
   display: grid;
-  grid-template-columns: repeat(4, minmax(0, 1fr));
+  grid-template-columns: repeat(3, minmax(0, 1fr));
   gap: 8px;
-  margin: 0;
 }
 
-.debug-overlay__metrics > div {
+.debug-overlay__vital {
+  position: relative;
+  display: flex;
+  flex-direction: column;
   min-width: 0;
-  padding: 8px;
+  overflow: hidden;
+  padding: 8px 10px 0;
   background: var(--bg-hover);
   border: 1px solid var(--border);
   border-radius: var(--radius-sm);
+  /* currentColor drives every chart part; degraded flips one token below. */
+  color: var(--accent-2);
 }
 
-.debug-overlay__metrics dt {
+.debug-overlay__vital[data-degraded] {
+  color: var(--danger);
+  border-color: color-mix(in srgb, var(--danger) 35%, var(--border));
+}
+
+.debug-overlay__head {
+  display: flex;
+  gap: 6px;
+  align-items: baseline;
+  justify-content: space-between;
+}
+
+.debug-vital__label {
+  overflow: hidden;
+  color: var(--muted);
+  font-size: 9.5px;
+  letter-spacing: 0.08em;
+  white-space: nowrap;
+  text-transform: uppercase;
+}
+
+.debug-vital__sub {
   overflow: hidden;
   color: var(--muted);
   font-size: 10px;
-  text-overflow: ellipsis;
   white-space: nowrap;
 }
 
-.debug-overlay__metrics dd {
-  margin: 3px 0 0;
-  font-size: 12px;
+.debug-vital__value {
+  margin: 3px 0 2px;
+  color: var(--text);
+  font-size: 16px;
+  line-height: 1.2;
+}
+
+.debug-vital__age {
+  margin-left: 4px;
+  color: var(--muted);
+  font-size: 10px;
+}
+
+.debug-vital__chart {
+  position: relative;
+  margin: auto -10px 0;
+}
+
+.debug-vital__chart svg {
+  display: block;
+  width: 100%;
+  height: 40px;
+}
+
+.debug-vital__chart polyline {
+  fill: none;
+  stroke: currentColor;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  stroke-width: 1.5;
+  vector-effect: non-scaling-stroke;
+  filter: drop-shadow(0 0 4px color-mix(in srgb, currentColor 45%, transparent));
+}
+
+.debug-vital__hairline {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 1px;
+  background: color-mix(in srgb, currentColor 40%, transparent);
+  pointer-events: none;
+}
+
+.debug-vital__dot {
+  position: absolute;
+  width: 5px;
+  height: 5px;
+  background: currentColor;
+  border-radius: 50%;
+  transform: translate(-50%, -50%);
+  pointer-events: none;
+}
+
+.debug-vital__dot--now {
+  box-shadow: 0 0 6px 1px color-mix(in srgb, currentColor 60%, transparent);
+  animation: debug-vital-pulse 2s ease-in-out infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .debug-vital__dot--now {
+    animation: none;
+  }
+}
+
+@keyframes debug-vital-pulse {
+  50% {
+    box-shadow: 0 0 2px 0 color-mix(in srgb, currentColor 30%, transparent);
+  }
+}
+
+.debug-overlay__vitals-footer {
+  margin-top: 8px;
+  color: var(--muted);
+  font-size: 10px;
+  text-align: right;
 }
 
 .debug-overlay__count,
@@ -196,7 +293,7 @@ openclaw-debug-overlay {
     max-height: calc(100vh - 16px);
   }
 
-  .debug-overlay__metrics {
-    grid-template-columns: repeat(2, minmax(0, 1fr));
+  .debug-overlay__vitals {
+    grid-template-columns: minmax(0, 1fr);
   }
 }

From c801579020472dd55f2380db66c7851446572fe1 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 15:20:58 -0700
Subject: [PATCH 108/124] fix(onboard): keep provider credentials with named
 first agents (#127572)

* fix(onboard): keep provider credentials with named first agents

* fix(onboard): preserve workspace in provider choice normalization
---
 .../auth-choice.apply.api-providers.test.ts   | 111 ++++++++++++++++++
 src/commands/auth-choice.apply.ts             |  23 ++--
 src/commands/auth-choice.apply.types.ts       |   1 +
 src/commands/onboard-agent-target.test.ts     |  61 +++++++++-
 src/commands/onboard-agent-target.ts          |  20 +++-
 .../local.default-agent.test.ts               |  27 ++++-
 src/commands/onboard-non-interactive/local.ts |   9 +-
 .../local/auth-choice.test.ts                 |  29 +++++
 .../local/auth-choice.ts                      |   1 +
 src/wizard/setup.model-auth.test.ts           |  37 ++++++
 src/wizard/setup.model-auth.ts                |  20 ++--
 src/wizard/setup.ts                           |   4 +-
 12 files changed, 301 insertions(+), 42 deletions(-)

diff --git a/src/commands/auth-choice.apply.api-providers.test.ts b/src/commands/auth-choice.apply.api-providers.test.ts
index 8af6ec339ee0..8e820ffc2e9f 100644
--- a/src/commands/auth-choice.apply.api-providers.test.ts
+++ b/src/commands/auth-choice.apply.api-providers.test.ts
@@ -1,17 +1,35 @@
 // API-provider auth-choice tests cover built-in provider config, API keys, and provider plugin setup.
 import { afterEach, describe, expect, it, vi } from "vitest";
+import * as providerAuthChoices from "../plugins/provider-auth-choices.js";
 import type { ProviderPlugin } from "../plugins/types.js";
 import { normalizeApiKeyTokenProviderAuthChoice } from "./auth-choice.apply.api-providers.js";
+import { prepareAuthChoice } from "./auth-choice.apply.js";
 
 const resolvePluginProviders = vi.hoisted(() =>
   vi.fn<typeof import("../plugins/provider-auth-choice.runtime.js").resolvePluginProviders>(),
 );
 const resolvePluginSetupProvider = vi.hoisted(() => vi.fn(() => undefined));
+const prepareAuthChoiceLoadedPluginProvider = vi.hoisted(() =>
+  vi.fn<
+    typeof import("../plugins/provider-auth-choice.js").prepareAuthChoiceLoadedPluginProvider
+  >(),
+);
+const resolveDeprecatedProviderInstallCatalogEntry = vi.hoisted(() =>
+  vi.fn<
+    typeof import("../plugins/provider-install-catalog.js").resolveDeprecatedProviderInstallCatalogEntry
+  >(),
+);
 
 vi.mock("../plugins/provider-auth-choice.runtime.js", () => ({
   resolvePluginProviders,
   resolvePluginSetupProvider,
 }));
+vi.mock("../plugins/provider-auth-choice.js", () => ({
+  prepareAuthChoiceLoadedPluginProvider,
+}));
+vi.mock("../plugins/provider-install-catalog.js", () => ({
+  resolveDeprecatedProviderInstallCatalogEntry,
+}));
 
 function createProvider(params: {
   id: string;
@@ -39,6 +57,9 @@ function createProvider(params: {
 describe("normalizeApiKeyTokenProviderAuthChoice", () => {
   afterEach(() => {
     resolvePluginProviders.mockReset();
+    prepareAuthChoiceLoadedPluginProvider.mockReset();
+    resolveDeprecatedProviderInstallCatalogEntry.mockReset();
+    vi.restoreAllMocks();
   });
 
   it("maps token provider auth through plugin token methods", () => {
@@ -89,4 +110,94 @@ describe("normalizeApiKeyTokenProviderAuthChoice", () => {
       }),
     ).toBe("token");
   });
+
+  it.each([
+    { authChoice: "apiKey", kind: "api_key" },
+    { authChoice: "token", kind: "token" },
+    { authChoice: "setup-token", kind: "token" },
+  ] as const)(
+    "resolves workspace-only $authChoice providers through interactive setup",
+    async (choice) => {
+      const workspaceDir = "/tmp/selected-agent-workspace";
+      const provider = createProvider({
+        id: "workspace-provider",
+        auth: [{ id: "workspace-auth", kind: choice.kind, choiceId: "workspace-provider-auth" }],
+      });
+      resolvePluginProviders.mockImplementation((params) =>
+        params?.workspaceDir === workspaceDir ? [provider] : [],
+      );
+      prepareAuthChoiceLoadedPluginProvider.mockImplementation(async (params) =>
+        params.authChoice === "workspace-provider-auth"
+          ? {
+              config: params.config,
+              authProfiles: [
+                {
+                  profileId: "workspace-provider:default",
+                  credential: {
+                    type: "api_key",
+                    provider: "workspace-provider",
+                    key: "fixture-workspace-key",
+                  },
+                },
+              ],
+              persistAuthProfiles: async () => {},
+            }
+          : null,
+      );
+
+      const prepared = await prepareAuthChoice({
+        authChoice: choice.authChoice,
+        config: {},
+        workspaceDir,
+        prompter: {} as never,
+        runtime: {} as never,
+        setDefaultModel: false,
+        opts: { tokenProvider: provider.id },
+      });
+
+      expect(prepared.authProfiles).toEqual([
+        {
+          profileId: "workspace-provider:default",
+          credential: {
+            type: "api_key",
+            provider: "workspace-provider",
+            key: "fixture-workspace-key",
+          },
+        },
+      ]);
+    },
+  );
+
+  it.each(["manifest", "install catalog"] as const)(
+    "resolves workspace-only deprecated auth choices from the %s",
+    async (source) => {
+      const workspaceDir = "/tmp/selected-agent-workspace";
+      vi.spyOn(
+        providerAuthChoices,
+        "resolveManifestDeprecatedProviderAuthChoice",
+      ).mockImplementation((_choice, params) =>
+        source === "manifest" && params?.workspaceDir === workspaceDir
+          ? ({ choiceId: "workspace-modern-auth" } as never)
+          : undefined,
+      );
+      resolveDeprecatedProviderInstallCatalogEntry.mockImplementation((_choice, params) =>
+        source === "install catalog" &&
+        params?.workspaceDir === workspaceDir &&
+        params.includeUntrustedWorkspacePlugins === false
+          ? ({ choiceId: "workspace-modern-auth" } as never)
+          : undefined,
+      );
+
+      await expect(
+        prepareAuthChoice({
+          authChoice: "workspace-legacy-auth",
+          config: {},
+          workspaceDir,
+          prompter: {} as never,
+          runtime: {} as never,
+          setDefaultModel: false,
+        }),
+      ).rejects.toThrow('Use "workspace-modern-auth" instead');
+    },
+  );
 });
diff --git a/src/commands/auth-choice.apply.ts b/src/commands/auth-choice.apply.ts
index 26c242667848..10bc1d9df5cd 100644
--- a/src/commands/auth-choice.apply.ts
+++ b/src/commands/auth-choice.apply.ts
@@ -10,7 +10,7 @@ import type { AuthChoice } from "./onboard-types.js";
 
 async function normalizeLegacyChoice(
   authChoice: AuthChoice | undefined,
-  params: Pick<ApplyAuthChoiceParams, "config" | "env">,
+  params: Pick<ApplyAuthChoiceParams, "config" | "env" | "workspaceDir">,
 ): Promise<AuthChoice | undefined> {
   if (authChoice === "oauth") {
     return "setup-token";
@@ -42,31 +42,28 @@ async function normalizeTokenProviderChoice(params: {
     authChoice: params.authChoice,
     tokenProvider: params.source.opts.tokenProvider,
     config: params.source.config,
+    workspaceDir: params.source.workspaceDir,
     env: params.source.env,
   });
 }
 
 async function formatDeprecatedProviderChoiceError(
   authChoice: AuthChoice | undefined,
-  params: Pick<ApplyAuthChoiceParams, "config" | "env">,
+  params: Pick<ApplyAuthChoiceParams, "config" | "env" | "workspaceDir">,
 ): Promise<string | undefined> {
   if (typeof authChoice !== "string") {
     return undefined;
   }
   const { resolveManifestDeprecatedProviderAuthChoice } =
     await import("../plugins/provider-auth-choices.js");
-  const deprecatedChoice = resolveManifestDeprecatedProviderAuthChoice(authChoice, {
-    config: params.config,
-    env: params.env,
-  });
+  const deprecatedChoice = resolveManifestDeprecatedProviderAuthChoice(authChoice, params);
   if (deprecatedChoice) {
     return `Auth choice ${JSON.stringify(authChoice)} is no longer supported. Use ${JSON.stringify(deprecatedChoice.choiceId)} instead, or run ${formatCliCommand("openclaw onboard")} to choose interactively.`;
   }
   const { resolveDeprecatedProviderInstallCatalogEntry } =
     await import("../plugins/provider-install-catalog.js");
   const externalDeprecatedChoice = resolveDeprecatedProviderInstallCatalogEntry(authChoice, {
-    config: params.config,
-    env: params.env,
+    ...params,
     includeUntrustedWorkspacePlugins: false,
   });
   if (!externalDeprecatedChoice) {
@@ -80,10 +77,7 @@ export async function prepareAuthChoice(
   params: ApplyAuthChoiceParams,
 ): Promise<PreparedAuthChoiceResult> {
   const normalizedAuthChoice =
-    (await normalizeLegacyChoice(params.authChoice, {
-      config: params.config,
-      env: params.env,
-    })) ?? params.authChoice;
+    (await normalizeLegacyChoice(params.authChoice, params)) ?? params.authChoice;
   const normalizedProviderAuthChoice = await normalizeTokenProviderChoice({
     authChoice: normalizedAuthChoice,
     source: params,
@@ -99,10 +93,7 @@ export async function prepareAuthChoice(
 
   const deprecatedProviderChoiceError = await formatDeprecatedProviderChoiceError(
     normalizedParams.authChoice,
-    {
-      config: normalizedParams.config,
-      env: normalizedParams.env,
-    },
+    normalizedParams,
   );
   if (deprecatedProviderChoiceError) {
     throw new Error(deprecatedProviderChoiceError);
diff --git a/src/commands/auth-choice.apply.types.ts b/src/commands/auth-choice.apply.types.ts
index 265d8e6f93c1..fdc34a965aca 100644
--- a/src/commands/auth-choice.apply.types.ts
+++ b/src/commands/auth-choice.apply.types.ts
@@ -12,6 +12,7 @@ export type ApplyAuthChoiceParams = {
   prompter: WizardPrompter;
   runtime: RuntimeEnv;
   agentDir?: string;
+  workspaceDir?: string;
   setDefaultModel: boolean;
   preserveExistingDefaultModel?: boolean;
   agentId?: string;
diff --git a/src/commands/onboard-agent-target.test.ts b/src/commands/onboard-agent-target.test.ts
index 5d2afccee787..eb4a93dc7f74 100644
--- a/src/commands/onboard-agent-target.test.ts
+++ b/src/commands/onboard-agent-target.test.ts
@@ -78,22 +78,71 @@ describe("onboarding agent target", () => {
       main: { workspace: "/srv/main" },
       ops: { default: true, workspace: "/srv/ops" },
     };
+    const pendingAgent = { name: "robby", workspaceDir: "/srv/robby" };
 
     expect(
-      resolveOnboardingSetupTarget({
-        agents: {
-          ownership: "explicit",
-          defaults: { systemAgent: { agentId: "main" } },
-          entries,
+      resolveOnboardingSetupTarget(
+        {
+          agents: {
+            ownership: "explicit",
+            defaults: { systemAgent: { agentId: "main" } },
+            entries,
+          },
         },
-      }),
+        pendingAgent,
+      ),
     ).toMatchObject({ agentId: "main", workspaceDir: "/srv/main" });
+    expect(
+      resolveOnboardingSetupTarget(
+        {
+          agents: {
+            ownership: "explicit",
+            defaults: { systemAgent: { agentId: "main" } },
+            entries: { main: { default: true } },
+          },
+        },
+        pendingAgent,
+      ),
+    ).toMatchObject({ agentId: "main" });
     expect(resolveOnboardingSetupTarget({ agents: { entries } })).toMatchObject({
       agentId: "ops",
       workspaceDir: "/srv/ops",
     });
   });
 
+  it("resolves a pending first agent without nesting the selected workspace", async () => {
+    const stateDir = tempDirs.make("openclaw-pending-onboard-target-");
+    const workspaceDir = path.join(stateDir, "requested-workspace");
+
+    await withEnvAsync({ OPENCLAW_STATE_DIR: stateDir }, async () => {
+      for (const entries of [undefined, { main: {} }, { main: { default: true } }] as const) {
+        const config = {
+          agents: { defaults: { workspace: workspaceDir }, ...(entries ? { entries } : {}) },
+        };
+
+        expect(resolveOnboardingSetupTarget(config, { name: " Robby! ", workspaceDir })).toEqual({
+          agentId: "robby",
+          agentDir: path.join(stateDir, "agents", "robby", "agent"),
+          workspaceDir,
+        });
+        expect(resolveOnboardingSetupTarget(config)).toMatchObject({
+          agentId: "main",
+          workspaceDir,
+        });
+      }
+      expect(
+        resolveOnboardingSetupTarget({
+          agents: {
+            entries: { main: { default: true, name: "Authored main", workspace: "/srv/main" } },
+          },
+        }),
+      ).toMatchObject({ agentId: "main", workspaceDir: "/srv/main" });
+      expect(
+        resolveOnboardingSetupTarget({ agents: { entries: { main: { default: false } } } }),
+      ).toMatchObject({ agentId: "main" });
+    });
+  });
+
   it("keeps explicit agent model mutations on the system-agent entry", () => {
     const config = {
       agents: {
diff --git a/src/commands/onboard-agent-target.ts b/src/commands/onboard-agent-target.ts
index 15f8a86a52ff..9dd410766cac 100644
--- a/src/commands/onboard-agent-target.ts
+++ b/src/commands/onboard-agent-target.ts
@@ -48,11 +48,21 @@ export function resolveSystemAgentOnboardingTarget(config: OpenClawConfig): Onbo
   return resolveOnboardingAgentTarget(config, config.agents?.defaults?.systemAgent?.agentId);
 }
 
-/** Resolve onboarding setup to the system agent only for explicitly owned fleets. */
-export function resolveOnboardingSetupTarget(config: OpenClawConfig): OnboardingAgentTarget {
-  return config.agents?.ownership === "explicit"
-    ? resolveSystemAgentOnboardingTarget(config)
-    : resolveOnboardingAgentTarget(config);
+/** Resolve onboarding setup to its existing or pending first-agent owner. */
+export function resolveOnboardingSetupTarget(
+  config: OpenClawConfig,
+  pendingAgent?: { name: string; workspaceDir: string },
+): OnboardingAgentTarget {
+  if (config.agents?.ownership === "explicit") {
+    return resolveSystemAgentOnboardingTarget(config);
+  }
+  if (pendingAgent) {
+    return {
+      ...resolveOnboardingAgentTarget(config, pendingAgent.name),
+      workspaceDir: pendingAgent.workspaceDir,
+    };
+  }
+  return resolveOnboardingAgentTarget(config);
 }
 
 export async function ensureOnboardingAgentWorkspace(
diff --git a/src/commands/onboard-non-interactive/local.default-agent.test.ts b/src/commands/onboard-non-interactive/local.default-agent.test.ts
index 6ef8acbfcc0e..5f707c22d349 100644
--- a/src/commands/onboard-non-interactive/local.default-agent.test.ts
+++ b/src/commands/onboard-non-interactive/local.default-agent.test.ts
@@ -198,7 +198,6 @@ describe("runNonInteractiveLocalSetup default-agent ownership", () => {
               robby: {
                 name: "robby",
                 workspace,
-                agentDir: "/tmp/robby-agent",
               },
             },
           },
@@ -215,7 +214,7 @@ describe("runNonInteractiveLocalSetup default-agent ownership", () => {
         mode: "local",
         agentName: "robby",
         workspace,
-        authChoice: "skip",
+        authChoice: "demo-api-key",
         skipHooks: true,
         skipSkills: true,
         skipHealth: true,
@@ -225,6 +224,18 @@ describe("runNonInteractiveLocalSetup default-agent ownership", () => {
       baseConfig: {},
     });
 
+    expect(mocks.applyAuthChoice).toHaveBeenCalledWith(
+      expect.objectContaining({
+        target: expect.objectContaining({
+          agentId: "robby",
+          agentDir: expect.stringMatching(/[/\\]agents[/\\]robby[/\\]agent$/),
+          workspaceDir: workspace,
+        }),
+      }),
+    );
+    expect(mocks.applyAuthChoice.mock.invocationCallOrder[0]).toBeLessThan(
+      mocks.ensureOnboardingAgent.mock.invocationCallOrder[0]!,
+    );
     expect(mocks.ensureOnboardingAgent).toHaveBeenCalledOnce();
     expect(mocks.ensureOnboardingAgent).toHaveBeenCalledWith(
       expect.objectContaining({ firstAgent: { name: "robby" } }),
@@ -306,8 +317,9 @@ describe("runNonInteractiveLocalSetup default-agent ownership", () => {
       opts: {
         nonInteractive: true,
         mode: "local",
+        agentName: "robby",
         workspace: "/tmp/global-workspace",
-        authChoice: "skip",
+        authChoice: "demo-api-key",
         skipHooks: true,
         skipSkills: true,
         skipHealth: true,
@@ -318,6 +330,15 @@ describe("runNonInteractiveLocalSetup default-agent ownership", () => {
       baseConfig,
     });
 
+    expect(mocks.applyAuthChoice).toHaveBeenCalledWith(
+      expect.objectContaining({
+        target: expect.objectContaining({
+          agentId: "ops",
+          agentDir: "/tmp/ops-agent",
+          workspaceDir: "/tmp/ops-workspace",
+        }),
+      }),
+    );
     expect(mocks.commitConfig).toHaveBeenCalledWith(
       expect.objectContaining({
         nextConfig: expect.objectContaining({
diff --git a/src/commands/onboard-non-interactive/local.ts b/src/commands/onboard-non-interactive/local.ts
index 64e061f3fded..b7978e3e03f7 100644
--- a/src/commands/onboard-non-interactive/local.ts
+++ b/src/commands/onboard-non-interactive/local.ts
@@ -4,6 +4,7 @@
  * This entrypoint applies config changes, optionally installs the gateway
  * daemon, verifies health, and emits machine-readable setup output.
  */
+import { listAgentEntries } from "../../agents/agent-scope-config.js";
 import { formatCliCommand } from "../../cli/command-format.js";
 import { resolveGatewayPort } from "../../config/config.js";
 import { logConfigUpdated } from "../../config/logging.js";
@@ -178,7 +179,6 @@ export async function runNonInteractiveLocalSetup(params: {
 }) {
   const { opts, runtime, baseConfig, baseHash } = params;
   const mode = "local" as const;
-  const preCreationAgentId = resolveOnboardingSetupTarget(baseConfig).agentId;
 
   const requestedWorkspaceDir = resolveNonInteractiveWorkspaceDir({
     opts,
@@ -207,7 +207,12 @@ export async function runNonInteractiveLocalSetup(params: {
   }
   // Workspace defaults are already staged above; provider discovery must use
   // that requested owner before first-agent creation is allowed to write.
-  const authTarget = resolveOnboardingAgentTarget(nextConfig, preCreationAgentId);
+  const authTarget = resolveOnboardingSetupTarget(
+    nextConfig,
+    opts.agentName && listAgentEntries(baseConfig).length === 0
+      ? { name: opts.agentName, workspaceDir }
+      : undefined,
+  );
 
   const inferredAuthChoice = opts.authChoice
     ? undefined
diff --git a/src/commands/onboard-non-interactive/local/auth-choice.test.ts b/src/commands/onboard-non-interactive/local/auth-choice.test.ts
index 95509661b1a9..7ce186e5c96d 100644
--- a/src/commands/onboard-non-interactive/local/auth-choice.test.ts
+++ b/src/commands/onboard-non-interactive/local/auth-choice.test.ts
@@ -2,6 +2,7 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../../config/config.js";
 import { resolveAgentModelPrimaryValue } from "../../../config/model-input.js";
+import * as apiProviderAuthChoices from "../../auth-choice.apply.api-providers.js";
 import { commitNonInteractiveOnboardConfig } from "../config-write.js";
 import { applyNonInteractiveAuthChoice } from "./auth-choice.js";
 
@@ -107,6 +108,34 @@ describe("applyNonInteractiveAuthChoice", () => {
     expect(runtime.exit).not.toHaveBeenCalled();
   });
 
+  it("resolves generic provider auth from the selected agent workspace", async () => {
+    const runtime = createRuntime();
+    const nextConfig = { agents: { defaults: {} } } as OpenClawConfig;
+    const resolvedConfig = { auth: { profiles: { "demo-provider:default": { mode: "api_key" } } } };
+    applyNonInteractivePluginProviderChoice.mockResolvedValueOnce(resolvedConfig as never);
+    const normalize = vi
+      .spyOn(apiProviderAuthChoices, "normalizeApiKeyTokenProviderAuthChoice")
+      .mockImplementation((params) =>
+        params.workspaceDir === target.workspaceDir ? "demo-provider-api-key" : params.authChoice,
+      );
+
+    try {
+      const result = await applyNonInteractiveAuthChoice({
+        nextConfig,
+        authChoice: "apiKey",
+        opts: { tokenProvider: "demo-provider" },
+        runtime: runtime as never,
+        baseConfig: nextConfig,
+        target,
+      });
+
+      expect(result).toBe(resolvedConfig);
+      expect(runtime.error).not.toHaveBeenCalled();
+    } finally {
+      normalize.mockRestore();
+    }
+  });
+
   it("resolves plugin provider auth before builtin custom-provider handling", async () => {
     const runtime = createRuntime();
     const nextConfig = { agents: { defaults: {} } } as OpenClawConfig;
diff --git a/src/commands/onboard-non-interactive/local/auth-choice.ts b/src/commands/onboard-non-interactive/local/auth-choice.ts
index 32b8517b9fcc..6ed65fbc339c 100644
--- a/src/commands/onboard-non-interactive/local/auth-choice.ts
+++ b/src/commands/onboard-non-interactive/local/auth-choice.ts
@@ -50,6 +50,7 @@ export async function applyNonInteractiveAuthChoice(params: {
     authChoice: params.authChoice,
     tokenProvider: opts.tokenProvider,
     config: params.nextConfig,
+    workspaceDir: params.target.workspaceDir,
     env: process.env,
   });
   const nextConfig = params.nextConfig;
diff --git a/src/wizard/setup.model-auth.test.ts b/src/wizard/setup.model-auth.test.ts
index ba0ca03a9f4b..8443f04cca38 100644
--- a/src/wizard/setup.model-auth.test.ts
+++ b/src/wizard/setup.model-auth.test.ts
@@ -152,6 +152,43 @@ describe("runSetupModelAuthStep", () => {
     });
   });
 
+  it("stages provider auth on the pending named agent without nesting its workspace", async () => {
+    const workspaceDir = "/tmp/robby-workspace";
+    const config: OpenClawConfig = { agents: { defaults: { workspace: workspaceDir } } };
+    promptAuthChoiceGrouped.mockResolvedValueOnce("anthropic-cli");
+    applyAuthChoice.mockResolvedValueOnce({
+      config,
+      authProfiles: [],
+      persistAuthProfiles: async () => {},
+    });
+
+    await runSetupModelAuthStep({
+      config,
+      opts: {},
+      pendingAgent: { name: "Robby!", workspaceDir },
+      prompter: createPrompter(),
+      runtime: createRuntime(),
+    });
+
+    const agentDir = expect.stringMatching(/[/\\]agents[/\\]robby[/\\]agent$/);
+    expect(ensureAuthProfileStore).toHaveBeenCalledWith(agentDir, {
+      allowKeychainPrompt: false,
+      readOnly: true,
+    });
+    expect(promptAuthChoiceGrouped).toHaveBeenCalledWith(expect.objectContaining({ workspaceDir }));
+    expect(applyAuthChoice).toHaveBeenCalledWith(
+      expect.objectContaining({ agentId: "robby", agentDir, workspaceDir }),
+    );
+    expect(promptDefaultModel).toHaveBeenCalledWith(
+      expect.objectContaining({ agentId: "robby", agentDir, workspaceDir }),
+    );
+    expect(warnIfModelConfigLooksOff).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.anything(),
+      expect.objectContaining({ agentId: "robby", agentDir }),
+    );
+  });
+
   it("targets the system agent when an explicit fleet selects Claude CLI", async () => {
     const config: OpenClawConfig = {
       agents: {
diff --git a/src/wizard/setup.model-auth.ts b/src/wizard/setup.model-auth.ts
index c96cb5372299..2327d9efd6c8 100644
--- a/src/wizard/setup.model-auth.ts
+++ b/src/wizard/setup.model-auth.ts
@@ -126,6 +126,7 @@ export async function runSetupModelAuthStep(params: {
   runtime: RuntimeEnv;
   agentDir?: string;
   stateDir?: string;
+  pendingAgent?: { name: string; workspaceDir: string };
   preserveExistingModelSelection?: boolean;
 }): Promise<SetupModelAuthCandidate> {
   const { opts, prompter, runtime } = params;
@@ -148,6 +149,8 @@ export async function runSetupModelAuthStep(params: {
     | (typeof import("../commands/auth-choice-prompt.js"))["isKeepCurrentAuthChoice"]
     | undefined;
   let detectedProviderIds: ReadonlySet<string> | undefined;
+  const resolveTarget = (config: OpenClawConfig) =>
+    resolveOnboardingSetupTarget(config, params.pendingAgent);
   if (authChoiceFromPrompt) {
     const [
       { ensureAuthProfileStore },
@@ -160,7 +163,7 @@ export async function runSetupModelAuthStep(params: {
     ]);
     promptAuthChoiceGrouped = promptAuthChoice;
     isKeepCurrentAuthChoice = isKeepCurrentChoice;
-    const target = resolveOnboardingSetupTarget(nextConfig);
+    const target = resolveTarget(nextConfig);
     authStore = ensureAuthProfileStore(params.agentDir ?? target.agentDir, {
       allowKeychainPrompt: false,
       readOnly: true,
@@ -173,7 +176,7 @@ export async function runSetupModelAuthStep(params: {
   }
   while (true) {
     if (authChoiceFromPrompt) {
-      const target = resolveOnboardingSetupTarget(nextConfig);
+      const target = resolveTarget(nextConfig);
       authChoice = await promptAuthChoiceGrouped!({
         prompter,
         store: authStore!,
@@ -214,7 +217,7 @@ export async function runSetupModelAuthStep(params: {
       // or run model/auth checks when the caller already chose to skip setup.
       if (authChoiceFromPrompt) {
         const { promptDefaultModel } = await loadModelPickerModule();
-        const target = resolveOnboardingSetupTarget(nextConfig);
+        const target = resolveTarget(nextConfig);
         const modelSelection = await promptDefaultModel({
           config: nextConfig,
           prompter,
@@ -235,7 +238,7 @@ export async function runSetupModelAuthStep(params: {
         }
 
         const { warnIfModelConfigLooksOff } = await loadAuthChoiceModule();
-        const validationTarget = resolveOnboardingSetupTarget(nextConfig);
+        const validationTarget = resolveTarget(nextConfig);
         await warnIfModelConfigLooksOff(nextConfig, prompter, {
           agentId: validationTarget.agentId,
           agentDir: validationTarget.agentDir,
@@ -250,7 +253,7 @@ export async function runSetupModelAuthStep(params: {
       { promptDefaultModel },
     ] = await Promise.all([loadAuthChoiceModule(), loadModelPickerModule()]);
     prompter.disableBackNavigation?.();
-    const target = resolveOnboardingSetupTarget(nextConfig);
+    const target = resolveTarget(nextConfig);
     let authResult: PreparedAuthChoiceResult;
     try {
       authResult = await prepareAuthChoice({
@@ -260,6 +263,7 @@ export async function runSetupModelAuthStep(params: {
         runtime,
         agentId: target.agentId,
         agentDir: params.agentDir ?? target.agentDir,
+        workspaceDir: target.workspaceDir,
         setDefaultModel: true,
         preserveExistingDefaultModel: true,
         env,
@@ -292,7 +296,7 @@ export async function runSetupModelAuthStep(params: {
       break;
     }
     if (authResult.agentModelOverride) {
-      const overrideTarget = resolveOnboardingSetupTarget(nextConfig);
+      const overrideTarget = resolveTarget(nextConfig);
       nextConfig = applyOnboardingPrimaryModel(
         nextConfig,
         overrideTarget,
@@ -300,7 +304,7 @@ export async function runSetupModelAuthStep(params: {
       );
     }
 
-    const updatedTarget = resolveOnboardingSetupTarget(nextConfig);
+    const updatedTarget = resolveTarget(nextConfig);
     const authChoiceModelSelectionPolicy = await resolveAuthChoiceModelSelectionPolicy({
       authChoice,
       config: nextConfig,
@@ -334,7 +338,7 @@ export async function runSetupModelAuthStep(params: {
       }
     }
 
-    const validationTarget = resolveOnboardingSetupTarget(nextConfig);
+    const validationTarget = resolveTarget(nextConfig);
     await warnIfModelConfigLooksOff(nextConfig, prompter, {
       agentId: validationTarget.agentId,
       agentDir: validationTarget.agentDir,
diff --git a/src/wizard/setup.ts b/src/wizard/setup.ts
index 2387a85aed5f..7c327c704e51 100644
--- a/src/wizard/setup.ts
+++ b/src/wizard/setup.ts
@@ -527,13 +527,13 @@ async function runSetupWizardOnce(
   }
   const preModelAuthConfig = nextConfig;
   let stagedModelAuth: SetupModelAuthCandidate | undefined;
-  const hasExplicitAuthSetup = opts.authChoice !== undefined && opts.authChoice !== "skip";
-  if (!keepExistingModelConfig || hasExplicitAuthSetup) {
+  if (!keepExistingModelConfig || (opts.authChoice !== undefined && opts.authChoice !== "skip")) {
     stagedModelAuth = await runSetupModelAuthStep({
       config: nextConfig,
       opts,
       prompter,
       runtime,
+      pendingAgent: firstAgent && { ...firstAgent, workspaceDir },
       preserveExistingModelSelection: keepExistingModelConfig,
     });
     nextConfig = stagedModelAuth.config;

From d630897a95947156119bb0453f0e738366256bbb Mon Sep 17 00:00:00 2001
From: Jesse Merhi <79823012+jesse-merhi@users.noreply.github.com>
Date: Sat, 22 Aug 2026 08:27:37 +1000
Subject: [PATCH 109/124] fix(ui): show one session activity indicator
 (#123288)

* fix(ui): show one session activity indicator

* chore(ui): remove unused session unread renderer

* fix(ui): prioritize active child run indicators

* fix(ui): prioritize Home run activity

* test(ui): measure session endcap layout

* test(ui): align endcap atom count

* fix(ui): preserve hidden unread semantics

* fix(ui): announce active Home runs

* refactor(ui): centralize sidebar state descriptions

* fix(ui): compose Home activity description

---------

Co-authored-by: Jesse Merhi <jesse-merhi@users.noreply.github.com>
---
 ui/src/components/app-sidebar-render.ts       | 10 +++-
 .../app-sidebar-session-row-render.ts         | 10 ++--
 .../session-attention-presentation.ts         | 18 +++----
 .../components/session-leading-indicator.ts   | 13 ++---
 ...chat-flow.sidebar-presentation.e2e.test.ts |  2 +-
 ...sion-management.trailing-state.e2e.test.ts | 50 +++++++++++++------
 .../test-helpers/app-sidebar-cases/basics.ts  | 25 +++++++++-
 .../app-sidebar-cases/session-indicators.ts   | 35 +++++++++++--
 8 files changed, 118 insertions(+), 45 deletions(-)

diff --git a/ui/src/components/app-sidebar-render.ts b/ui/src/components/app-sidebar-render.ts
index ff95c1c03b0c..07ed829abce0 100644
--- a/ui/src/components/app-sidebar-render.ts
+++ b/ui/src/components/app-sidebar-render.ts
@@ -181,6 +181,12 @@ export function renderAppSidebarHomeRow(host: AppSidebarRenderHost) {
   const hasComposerDraft = host.hasSessionDraft(mainKey);
   const running = mainRow ? isSessionRunActive(mainRow) : false;
   const unread = mainRow?.unread === true && !active;
+  const activeRunLabel = running ? t("sessionsView.activeRun") : "";
+  const unreadLabel = unread ? t("sessionsView.unread") : "";
+  const homeDescription =
+    attentionLabel || (activeRunLabel && unreadLabel)
+      ? [attentionLabel, activeRunLabel, unreadLabel].filter(Boolean).join(" · ")
+      : "";
   // Home keeps its page/attention glyph leading and shares trailing activity with session rows.
   const homeGlyph = renderSessionGlyph({
     content:
@@ -188,7 +194,7 @@ export function renderAppSidebarHomeRow(host: AppSidebarRenderHost) {
         ? html`<span class="nav-item__icon" aria-hidden="true">${icons.home}</span>`
         : renderSessionAttentionIcon(attention),
     running: false,
-    badge: unread ? renderSessionUnreadBadge() : nothing,
+    badge: unread && !running ? renderSessionUnreadBadge() : nothing,
   });
   return html`
     <a
@@ -202,7 +208,7 @@ export function renderAppSidebarHomeRow(host: AppSidebarRenderHost) {
         preferenceDerivedFace: true,
       }).href}
       class="nav-item nav-item--home ${active ? "nav-item--active" : ""}"
-      aria-label=${attentionLabel ? `${t("nav.home")} · ${attentionLabel}` : nothing}
+      aria-label=${homeDescription ? `${t("nav.home")} · ${homeDescription}` : nothing}
       aria-current=${active ? "page" : nothing}
       @click=${(event: MouseEvent) => {
         if (!shouldHandleNavigationClick(event)) {
diff --git a/ui/src/components/app-sidebar-session-row-render.ts b/ui/src/components/app-sidebar-session-row-render.ts
index 08a570505347..58bb45b53255 100644
--- a/ui/src/components/app-sidebar-session-row-render.ts
+++ b/ui/src/components/app-sidebar-session-row-render.ts
@@ -220,11 +220,13 @@ export function renderRecentSession(params: {
       channelAvatarAuth,
     );
   const trailingDescription = session.isChild
-    ? ""
+    ? running && session.unread
+      ? t("sessionsView.unread")
+      : ""
     : describeSessionTrailingState(session, pullRequestState);
   const hasTrail = session.isChild && (session.runtimeMs != null || session.startedAt != null);
   const metaId = hasTrail ? sidebarSessionMetaId(session.key) : undefined;
-  const stateId = trailingIndicator === nothing ? undefined : sidebarSessionStateId(session.key);
+  const stateId = trailingDescription ? sidebarSessionStateId(session.key) : undefined;
   const openMenuFromEvent = (event: MouseEvent | KeyboardEvent) =>
     handleContextMenuEvent(
       event,
@@ -358,7 +360,9 @@ export function renderRecentSession(params: {
                 ),
               })}
               ${trailingIndicator === nothing
-                ? nothing
+                ? trailingDescription
+                  ? html`<span class="sr-only" id=${stateId}>${trailingDescription}</span>`
+                  : nothing
                 : html`<span class="session-row-aside">
                     <span
                       class="session-row-state"
diff --git a/ui/src/components/session-attention-presentation.ts b/ui/src/components/session-attention-presentation.ts
index 74fec5f2446b..5c0ecd2daa0b 100644
--- a/ui/src/components/session-attention-presentation.ts
+++ b/ui/src/components/session-attention-presentation.ts
@@ -41,16 +41,6 @@ export function sessionAttentionSubtitle(attention: SidebarSessionAttention): st
   }
 }
 
-export function renderSessionUnreadState(session: SidebarRecentSession) {
-  return !session.isChild && session.unread
-    ? html`<span
-        class="session-unread-dot sidebar-recent-session__unread"
-        role="img"
-        aria-label=${t("sessionsView.unread")}
-      ></span>`
-    : nothing;
-}
-
 export function renderSessionRunSpinner(showTitle = true) {
   return html`<span
     class="session-run-spinner sidebar-recent-session__state"
@@ -75,7 +65,13 @@ export function renderSessionState(session: SidebarRecentSession, showTitle = tr
     return renderSessionRunSpinner(showTitle);
   }
   if (!session.isChild) {
-    return renderSessionUnreadState(session);
+    return session.unread
+      ? html`<span
+          class="session-unread-dot sidebar-recent-session__unread"
+          role="img"
+          aria-label=${t("sessionsView.unread")}
+        ></span>`
+      : nothing;
   }
   const status = session.status;
   if (!status) {
diff --git a/ui/src/components/session-leading-indicator.ts b/ui/src/components/session-leading-indicator.ts
index 9cf585b075be..cb67965dd157 100644
--- a/ui/src/components/session-leading-indicator.ts
+++ b/ui/src/components/session-leading-indicator.ts
@@ -5,7 +5,6 @@ import { icons } from "./icons.ts";
 import {
   renderSessionAttentionIcon,
   renderSessionState,
-  renderSessionUnreadState,
 } from "./session-attention-presentation.ts";
 import {
   renderSessionGlyph,
@@ -33,7 +32,7 @@ function renderGlyphBadge(
   session: SidebarRecentSession,
   pullRequestState: SessionPullRequestIndicatorState,
 ): SessionGlyphContent {
-  if (session.unread) {
+  if (session.unread && !session.hasActiveRun) {
     return renderSessionUnreadBadge();
   }
   if (pullRequestState === "none") {
@@ -81,16 +80,10 @@ function renderSessionTrailingState(
   pullRequestState: SessionPullRequestIndicatorState,
 ) {
   const sessionState = renderSessionState(session, false);
-  const concurrentUnreadState = session.hasActiveRun ? renderSessionUnreadState(session) : nothing;
-  if (
-    pullRequestState === "none" &&
-    sessionState === nothing &&
-    concurrentUnreadState === nothing
-  ) {
+  if (pullRequestState === "none" && sessionState === nothing) {
     return nothing;
   }
-  return html`${renderPullRequestIndicator(pullRequestState, false)} ${sessionState}
-  ${concurrentUnreadState}`;
+  return html`${renderPullRequestIndicator(pullRequestState, false)} ${sessionState}`;
 }
 
 function renderPersistentSessionIcon(icon: string) {
diff --git a/ui/src/e2e/chat-flow.sidebar-presentation.e2e.test.ts b/ui/src/e2e/chat-flow.sidebar-presentation.e2e.test.ts
index 38295a65b490..f5749542911d 100644
--- a/ui/src/e2e/chat-flow.sidebar-presentation.e2e.test.ts
+++ b/ui/src/e2e/chat-flow.sidebar-presentation.e2e.test.ts
@@ -451,7 +451,7 @@ suite.define(() => {
       expect(layout.state.right).toBeLessThanOrEqual(layout.endcap.right);
       expect(layout.spinner.left).toBeGreaterThanOrEqual(layout.endcap.left);
       expect(layout.spinner.right).toBeLessThanOrEqual(layout.endcap.right);
-      expect(layout.atoms.length).toBeGreaterThanOrEqual(4);
+      expect(layout.atoms.length).toBeGreaterThanOrEqual(3);
       for (const atom of layout.atoms) {
         expect(atom.left).toBeGreaterThanOrEqual(layout.endcap.left);
         expect(atom.right).toBeLessThanOrEqual(layout.endcap.right);
diff --git a/ui/src/e2e/session-management.trailing-state.e2e.test.ts b/ui/src/e2e/session-management.trailing-state.e2e.test.ts
index 9ba2ce469b35..1a378c8bea64 100644
--- a/ui/src/e2e/session-management.trailing-state.e2e.test.ts
+++ b/ui/src/e2e/session-management.trailing-state.e2e.test.ts
@@ -363,21 +363,43 @@ suite.define(() => {
         .poll(() => state.locator("[data-session-pr-state='open']").isVisible())
         .toBe(true);
       await expect.poll(() => state.locator(".session-run-spinner").isVisible()).toBe(true);
-      await expect.poll(() => state.locator(".session-unread-dot").isVisible()).toBe(true);
-      const [endcapBounds, openPullRequestBounds, spinnerBounds, unreadBounds] = await Promise.all([
-        row.locator(".sidebar-recent-session__details-endcap").boundingBox(),
-        state.locator("[data-session-pr-state='open'] svg").boundingBox(),
-        state.locator(".session-run-spinner").boundingBox(),
-        state.locator(".session-unread-dot").boundingBox(),
-      ]);
-      if (!endcapBounds || !openPullRequestBounds || !spinnerBounds || !unreadBounds) {
-        throw new Error("Expected visible combined session state geometry");
-      }
-      for (const iconBounds of [openPullRequestBounds, spinnerBounds, unreadBounds]) {
-        expect(iconBounds.x).toBeGreaterThanOrEqual(endcapBounds.x);
-        expect(iconBounds.x + iconBounds.width).toBeLessThanOrEqual(
-          endcapBounds.x + endcapBounds.width,
+      await expect.poll(() => state.locator(".session-unread-dot").count()).toBe(0);
+      const stateLayout = await row.evaluate((element) => {
+        const endcap = element.querySelector<HTMLElement>(
+          ".sidebar-recent-session__details-endcap",
         );
+        const atoms = Array.from(
+          element.querySelectorAll<HTMLElement>(
+            ".session-row-state :is([data-session-pr-state='open'], .session-run-spinner)",
+          ),
+        );
+        if (!endcap || atoms.length !== 2) {
+          throw new Error("Expected visible session state geometry");
+        }
+        const layoutLeft = (node: HTMLElement) => {
+          let left = 0;
+          for (
+            let current: HTMLElement | null = node;
+            current;
+            current = current.offsetParent as HTMLElement | null
+          ) {
+            left += current.offsetLeft;
+          }
+          return left;
+        };
+        const endcapLeft = layoutLeft(endcap);
+        return {
+          endcapLeft,
+          endcapRight: endcapLeft + endcap.offsetWidth,
+          atoms: atoms.map((atom) => ({
+            left: layoutLeft(atom),
+            right: layoutLeft(atom) + atom.offsetWidth,
+          })),
+        };
+      });
+      for (const atom of stateLayout.atoms) {
+        expect(atom.left).toBeGreaterThanOrEqual(stateLayout.endcapLeft);
+        expect(atom.right).toBeLessThanOrEqual(stateLayout.endcapRight);
       }
       const link = row.locator(".sidebar-recent-session__link");
       const rowText = row.locator(".sidebar-recent-session__text");
diff --git a/ui/src/test-helpers/app-sidebar-cases/basics.ts b/ui/src/test-helpers/app-sidebar-cases/basics.ts
index 49f67bf43fcf..46156ae29d9b 100644
--- a/ui/src/test-helpers/app-sidebar-cases/basics.ts
+++ b/ui/src/test-helpers/app-sidebar-cases/basics.ts
@@ -331,7 +331,15 @@ describe("AppSidebar agent chip", () => {
         path: "",
         count: 1,
         defaults: { modelProvider: null, model: null, contextTokens: null },
-        sessions: [{ key: "agent:main:main", kind: "direct", updatedAt: 5, hasActiveRun: true }],
+        sessions: [
+          {
+            key: "agent:main:main",
+            kind: "direct",
+            updatedAt: 5,
+            hasActiveRun: true,
+            unread: true,
+          },
+        ],
       },
       agentId: "main",
     });
@@ -345,9 +353,24 @@ describe("AppSidebar agent chip", () => {
     expect(spinner).not.toBeNull();
     expect(sidebar.querySelector(".nav-item--home .nav-item__icon")).not.toBeNull();
     expect(sidebar.querySelector(".nav-item--home .session-glyph__ring")).toBeNull();
+    expect(sidebar.querySelector(".nav-item--home .session-glyph__badge--unread")).toBeNull();
     expect(spinner?.getAttribute("role")).toBe("img");
     expect(spinner?.getAttribute("aria-label")).toBe("Active run");
     expect(spinner?.getAttribute("title")).toBe("Active run");
+
+    harness.publishList({
+      result: {
+        ts: 3,
+        path: "",
+        count: 1,
+        defaults: { modelProvider: null, model: null, contextTokens: null },
+        sessions: [{ key: "agent:main:main", kind: "direct", updatedAt: 6, unread: true }],
+      },
+      agentId: "main",
+    });
+    await sidebar.updateComplete;
+    expect(sidebar.querySelector(".nav-item--home .session-run-spinner")).toBeNull();
+    expect(sidebar.querySelector(".nav-item--home .session-glyph__badge--unread")).not.toBeNull();
   });
 
   it("uses the shared tooltip for the Home dashboard glyph", async () => {
diff --git a/ui/src/test-helpers/app-sidebar-cases/session-indicators.ts b/ui/src/test-helpers/app-sidebar-cases/session-indicators.ts
index 189d4ac12883..58fd80710bf1 100644
--- a/ui/src/test-helpers/app-sidebar-cases/session-indicators.ts
+++ b/ui/src/test-helpers/app-sidebar-cases/session-indicators.ts
@@ -246,13 +246,16 @@ describe("AppSidebar session indicators", () => {
     for (const row of result.sessions) {
       row.hasActiveRun = true;
       row.status = "running";
+      if (row.key === mainKey) {
+        row.unread = true;
+      }
     }
     const { sidebar } = await mountSidebar(
       createGatewayHarness({} as GatewayBrowserClient).gateway,
       sessions.sessions,
     );
     sidebar.activeRouteId = "chat";
-    sidebar.sessionKey = mainKey;
+    sidebar.sessionKey = workingKey;
     sidebar.outboxAttentionCountForSession = (sessionKey) => (sessionKey === mainKey ? 2 : 0);
     sidebar.hasSessionDraft = (sessionKey) => sessionKey === mainKey;
     sidebar.requestUpdate();
@@ -271,6 +274,8 @@ describe("AppSidebar session indicators", () => {
     expect(homeSpinner?.getAttribute("aria-label")).toBe(
       sessionSpinner?.getAttribute("aria-label"),
     );
+    expect(home?.querySelector(".session-unread-dot")).toBeNull();
+    expect(home?.getAttribute("aria-label")).toBe("Home · Active run · Unread");
     expect(
       home?.querySelector(".nav-item__state .session-row-badge--attention")?.textContent,
     ).toContain("2");
@@ -354,6 +359,14 @@ describe("AppSidebar session indicators", () => {
           kind: "direct",
           label: "Open PR child",
           updatedAt: 2,
+          hasActiveRun: true,
+          status: "running",
+          unread: true,
+          agentStatus: {
+            note: "Waiting for input",
+            attention: "key",
+            expiresAt: Date.now() + 60_000,
+          },
           worktree: { id: "wt-open", branch: "feature/open", repoRoot: "/repo" },
         },
         {
@@ -419,9 +432,25 @@ describe("AppSidebar session indicators", () => {
     expect(pinnedLead?.innerHTML).toBe(runningLead?.innerHTML);
     expect(pinnedLead?.querySelector("[data-session-pr-state]")).toBeNull();
     expect(pinnedRow?.querySelector(".session-row-state")).toBeNull();
+
+    const attentionLead = sidebar.querySelector(
+      `[data-session-key="${openPullRequestKey}"] .sidebar-session-indicator`,
+    );
+    expect(attentionLead?.querySelector('[data-session-attention="agent"]')).not.toBeNull();
+    expect(attentionLead?.querySelector(".session-glyph__ring")).not.toBeNull();
+    expect(attentionLead?.querySelector(".session-glyph__badge--unread")).toBeNull();
+    expect(attentionLead?.querySelector('[data-session-pr-state="open"]')).not.toBeNull();
+    const attentionLink = sidebar.querySelector(
+      `[data-session-key="${openPullRequestKey}"] .sidebar-recent-session__link`,
+    );
+    const attentionDescriptionId = attentionLink?.getAttribute("aria-describedby");
+    expect(attentionDescriptionId).toBe(
+      `sidebar-session-state-${encodeURIComponent(openPullRequestKey)}`,
+    );
+    expect(sidebar.querySelector(`[id="${attentionDescriptionId}"]`)?.textContent).toBe("Unread");
   });
 
-  it("trails transient activity while keeping persistent status leading", async () => {
+  it("prioritizes an active run over unread activity", async () => {
     const keys = {
       plain: "agent:main:plain",
       forked: "agent:main:forked",
@@ -524,7 +553,7 @@ describe("AppSidebar session indicators", () => {
     ).not.toBeNull();
     expect(
       runningUnread?.querySelector(".session-row-aside > .session-row-state .session-unread-dot"),
-    ).not.toBeNull();
+    ).toBeNull();
 
     for (const key of [keys.unread, keys.runningUnread]) {
       const link = sidebar.querySelector(`[data-session-key="${key}"] a`);

From d54a8e80f22f118c4e02ed7d8099c838fdddd8b3 Mon Sep 17 00:00:00 2001
From: Josh Lehman <josh@martian.engineering>
Date: Fri, 21 Aug 2026 15:31:13 -0700
Subject: [PATCH 110/124] fix(ui): keep Home status clear of Pages editor
 (#127642)

---
 ui/src/e2e/sidebar-customization.e2e.test.ts | 88 ++++++++++++++++++++
 ui/src/styles/layout.css                     | 16 +++-
 2 files changed, 102 insertions(+), 2 deletions(-)

diff --git a/ui/src/e2e/sidebar-customization.e2e.test.ts b/ui/src/e2e/sidebar-customization.e2e.test.ts
index 01cdc0c7e902..c0a92d757e7b 100644
--- a/ui/src/e2e/sidebar-customization.e2e.test.ts
+++ b/ui/src/e2e/sidebar-customization.e2e.test.ts
@@ -691,6 +691,94 @@ suite.define(() => {
     );
   });
 
+  it("moves Home activity clear of the aligned Pages editor", async () => {
+    await suite.withPage(
+      {
+        locale: "en-US",
+        serviceWorkers: "block",
+        viewport: { height: 900, width: 1440 },
+      },
+      async ({ page }) => {
+        await installMockGateway(page, {
+          methodResponses: {
+            "sessions.list": {
+              count: 1,
+              defaults: {
+                contextTokens: null,
+                model: "gpt-5.5",
+                modelProvider: "openai",
+              },
+              path: "",
+              sessions: [
+                {
+                  hasActiveRun: true,
+                  key: "main",
+                  kind: "direct",
+                  status: "running",
+                  updatedAt: 100,
+                },
+              ],
+              ts: 100,
+            },
+          },
+        });
+
+        await page.goto(`${suite.server.baseUrl}chat`);
+        const sidebar = page.locator("openclaw-app-sidebar");
+        const home = sidebar.locator(".nav-item--home");
+        await expect.poll(() => home.isVisible()).toBe(true);
+        await sidebar.evaluate(async (element) => {
+          const host = element as HTMLElement & {
+            requestUpdate(): void;
+            updateComplete: Promise<unknown>;
+          };
+          // The shell refreshes this callback whenever its lazy outbox runtime
+          // loads. Keep the warning fixture stable until geometry is measured.
+          Object.defineProperty(host, "outboxAttentionCountForSession", {
+            configurable: true,
+            get: () => () => 1,
+            set: () => undefined,
+          });
+          host.requestUpdate();
+          await host.updateComplete;
+        });
+
+        const activity = home.locator(".sidebar-home-session-states");
+        const editor = sidebar.locator(".sidebar-nav__head-action");
+        await expect.poll(() => activity.locator(".session-run-spinner").count()).toBe(1);
+        await expect.poll(() => activity.locator(".session-row-badge--attention").count()).toBe(1);
+
+        await page.mouse.move(900, 400);
+        const restingActivity = await activity.boundingBox();
+        expect(restingActivity).not.toBeNull();
+        await sidebar.locator(".sidebar-nav").hover();
+        await expect
+          .poll(() => editor.evaluate((element) => getComputedStyle(element).opacity))
+          .toBe("1");
+        await expect
+          .poll(async () => {
+            const [homeBox, activityBox, editorBox] = await Promise.all([
+              home.boundingBox(),
+              activity.boundingBox(),
+              editor.boundingBox(),
+            ]);
+            if (!homeBox || !activityBox || !editorBox || !restingActivity) {
+              return null;
+            }
+            return {
+              activityShift: Math.round(restingActivity.x - activityBox.x),
+              centerDelta: Math.abs(
+                editorBox.y + editorBox.height / 2 - (homeBox.y + homeBox.height / 2),
+              ),
+              gap: Math.round(editorBox.x - (activityBox.x + activityBox.width)),
+            };
+          })
+          .toEqual({ activityShift: 25, centerDelta: 0, gap: 4 });
+        await captureUiProof(page, "07-home-activity-editor.png");
+      },
+    );
+  });
+
   it("keeps mobile attention in the drawer while desktop remains unchanged", async () => {
     await suite.withPage(
       {
diff --git a/ui/src/styles/layout.css b/ui/src/styles/layout.css
index fd14aad45ccc..0acd4e81fa30 100644
--- a/ui/src/styles/layout.css
+++ b/ui/src/styles/layout.css
@@ -3402,12 +3402,12 @@ wa-dropdown-item.session-menu__item::part(submenu-icon) {
 .sidebar-nav__head {
   position: absolute;
   z-index: 1;
-  top: 0;
+  top: 5px;
   right: 0;
   display: flex;
   align-items: center;
   justify-content: flex-end;
-  padding: 2px 8px 2px 12px;
+  padding: 0 8px 0 12px;
 }
 
 .sidebar-nav__head-action {
@@ -3440,6 +3440,10 @@ wa-dropdown-item.session-menu__item::part(submenu-icon) {
   .sidebar-nav__head-action {
     opacity: 1;
   }
+
+  .sidebar-home-session-states {
+    transform: translateX(-25px);
+  }
 }
 
 .sidebar-nav__head-action:hover,
@@ -3468,6 +3472,14 @@ wa-dropdown-item.session-menu__item::part(submenu-icon) {
   display: inline-flex;
   align-items: center;
   gap: 6px;
+  transition: transform var(--duration-fast) ease;
+}
+
+/* The Pages editor shares Home's row. Move every trailing state together so
+   its hover/focus hitbox never covers progress, warning, or draft status. */
+.sidebar-nav:hover .sidebar-home-session-states,
+.sidebar-nav:focus-within .sidebar-home-session-states {
+  transform: translateX(-25px);
 }
 
 /* Zone 5: product chrome in one slim footer bar. The shell footer's top

From fd0c9f6f96f20762ad13431310c821e30b9ea801 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 15:31:42 -0700
Subject: [PATCH 111/124] perf(tui): prepare searchable picker rows once
 (#127620)

Amp-Thread-ID: https://ampcode.com/threads/T-01a021f5-984a-7628-a30c-491c166ff247

Co-authored-by: Amp <amp@ampcode.com>
---
 src/tui/components/searchable-select-list.ts | 46 +++++++++++---------
 1 file changed, 26 insertions(+), 20 deletions(-)

diff --git a/src/tui/components/searchable-select-list.ts b/src/tui/components/searchable-select-list.ts
index 094565405646..a7b2b3de4ea9 100644
--- a/src/tui/components/searchable-select-list.ts
+++ b/src/tui/components/searchable-select-list.ts
@@ -34,6 +34,12 @@ export interface SearchableSelectItem extends SelectItem {
  */
 export class SearchableSelectList implements Component, Focusable {
   private items: SearchableSelectItem[];
+  private preparedItems?: Array<{
+    item: SearchableSelectItem;
+    label: string;
+    description: string;
+    searchText: string;
+  }>;
   private filteredItems: SearchableSelectItem[];
   private selectedIndex = 0;
   private maxVisible: number;
@@ -103,35 +109,35 @@ export class SearchableSelectList implements Component, Focusable {
     const scoredItems: ScoredItem[] = [];
     const fuzzyCandidates: FuzzyCandidate[] = [];
 
-    for (const item of this.items) {
-      const rawLabel = this.getItemLabel(item);
-      const rawDesc = item.description ?? "";
-      const label = normalizeLowercaseStringOrEmpty(stripAnsi(rawLabel));
-      const desc = normalizeLowercaseStringOrEmpty(stripAnsi(rawDesc));
-
+    // Rows are fixed for the overlay lifetime; defer search projection until it is needed.
+    this.preparedItems ??= this.items.map((item) => {
+      const label = stripAnsi(this.getItemLabel(item));
+      const description = stripAnsi(item.description ?? "");
+      const searchText = stripAnsi(item.searchText ?? "");
+      return {
+        item,
+        label: normalizeLowercaseStringOrEmpty(label),
+        description: normalizeLowercaseStringOrEmpty(description),
+        searchText: normalizeLowercaseStringOrEmpty(
+          [label, description, searchText].filter((value) => value.length > 0).join(" "),
+        ),
+      };
+    });
+    for (const prepared of this.preparedItems) {
       // Tier 1: Exact substring in label
-      const labelIndex = label.indexOf(q);
+      const labelIndex = prepared.label.indexOf(q);
       if (labelIndex !== -1) {
-        scoredItems.push({ item, tier: 0, score: labelIndex });
+        scoredItems.push({ item: prepared.item, tier: 0, score: labelIndex });
         continue;
       }
       // Tier 2: Exact substring in description
-      const descIndex = desc.indexOf(q);
+      const descIndex = prepared.description.indexOf(q);
       if (descIndex !== -1) {
-        scoredItems.push({ item, tier: 1, score: descIndex });
+        scoredItems.push({ item: prepared.item, tier: 1, score: descIndex });
         continue;
       }
       // Tier 3: Fuzzy match
-      const searchText = item.searchText ?? "";
-      fuzzyCandidates.push({
-        item,
-        searchText: normalizeLowercaseStringOrEmpty(
-          [rawLabel, rawDesc, searchText]
-            .map((value) => stripAnsi(value))
-            .filter((value) => value.length > 0)
-            .join(" "),
-        ),
-      });
+      fuzzyCandidates.push(prepared);
     }
 
     scoredItems.sort(this.compareByScore);

From 6d47044e7358a5d5376bc01ba7e23c4dcf542b4c Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 15:33:30 -0700
Subject: [PATCH 112/124] fix(ui): release stale model setup wizard sessions
 (#127657)

---
 .../model-setup/model-setup-page.test.ts      |   2 +-
 .../pages/model-setup/wizard-runner.test.ts   | 293 +++++++++++++++++-
 ui/src/pages/model-setup/wizard-runner.ts     |  71 ++++-
 3 files changed, 347 insertions(+), 19 deletions(-)

diff --git a/ui/src/pages/model-setup/model-setup-page.test.ts b/ui/src/pages/model-setup/model-setup-page.test.ts
index c76982ef28ce..24d69f2a68b6 100644
--- a/ui/src/pages/model-setup/model-setup-page.test.ts
+++ b/ui/src/pages/model-setup/model-setup-page.test.ts
@@ -322,7 +322,7 @@ describe("ModelSetupPage catalog icons", () => {
       expect(request).toHaveBeenCalledWith(
         "openclaw.setup.prepare.start",
         { sessionId: expect.any(String), agentId: "main", authChoice: "llama-cpp" },
-        expect.objectContaining({ signal: expect.any(AbortSignal) }),
+        { timeoutMs: null },
       );
       expect(page.querySelector("openclaw-modal-dialog")).not.toBeNull();
       expect(page.textContent).toContain("Downloading model: 25%");
diff --git a/ui/src/pages/model-setup/wizard-runner.test.ts b/ui/src/pages/model-setup/wizard-runner.test.ts
index 910e8e6e6f47..76ac4eafbe68 100644
--- a/ui/src/pages/model-setup/wizard-runner.test.ts
+++ b/ui/src/pages/model-setup/wizard-runner.test.ts
@@ -39,7 +39,7 @@ describe("ModelSetupWizardRunner", () => {
       1,
       "openclaw.setup.auth.start",
       { sessionId: expect.any(String), agentId: "research", authChoice: "openai-oauth" },
-      expect.objectContaining({ signal: expect.any(AbortSignal) }),
+      { timeoutMs: null },
     );
     expect(runner.state).toMatchObject({ phase: "step" });
     const answer = runner.answer(undefined, false);
@@ -119,7 +119,7 @@ describe("ModelSetupWizardRunner", () => {
       1,
       "openclaw.setup.prepare.start",
       { sessionId: expect.any(String), authChoice: "llama-cpp" },
-      expect.objectContaining({ signal: expect.any(AbortSignal) }),
+      { timeoutMs: null },
     );
     expect(runner.state).toMatchObject({
       phase: "step",
@@ -128,6 +128,295 @@ describe("ModelSetupWizardRunner", () => {
     });
   });
 
+  it.each([
+    ["openclaw.setup.auth.start", "cancel"],
+    ["openclaw.setup.auth.start", "settled cancel"],
+    ["openclaw.setup.auth.start", "close"],
+    ["openclaw.setup.prepare.start", "cancel"],
+    ["openclaw.setup.prepare.start", "settled cancel"],
+    ["openclaw.setup.prepare.start", "close"],
+  ] as const)(
+    "releases a late %s session after %s so setup can restart",
+    async (method, action) => {
+      let runningSession: string | null = null;
+      let firstSessionId = "";
+      let resolveFirstStart: () => void = () => {
+        throw new Error("the first setup request did not start");
+      };
+      let startCount = 0;
+      const request = vi.fn(
+        async (
+          requestMethod: string,
+          params?: { sessionId?: string },
+          options?: { signal?: AbortSignal },
+        ) => {
+          if (requestMethod === method) {
+            const sessionId = params?.sessionId;
+            if (!sessionId) {
+              throw new Error("missing setup session");
+            }
+            if (startCount++ === 0) {
+              firstSessionId = sessionId;
+              return await new Promise((resolve, reject) => {
+                options?.signal?.addEventListener(
+                  "abort",
+                  () => reject(new Error("Gateway retired the aborted start request")),
+                  { once: true },
+                );
+                resolveFirstStart = () => {
+                  runningSession = sessionId;
+                  resolve({ sessionId, done: false, status: "running" });
+                };
+              });
+            }
+            if (runningSession) {
+              throw new Error("wizard already running");
+            }
+            return { sessionId, done: true, status: "done" };
+          }
+          if (requestMethod === "wizard.cancel") {
+            if (runningSession !== params?.sessionId) {
+              throw new Error("wizard not found");
+            }
+            runningSession = null;
+            return { status: "cancelled" };
+          }
+          throw new Error(`unexpected request ${requestMethod}`);
+        },
+      );
+      const client = { request } as unknown as GatewayBrowserClient;
+      const runner = new ModelSetupWizardRunner({
+        getClient: () => client,
+        getAgentId: () => null,
+        onChange: () => undefined,
+        requestFailedMessage: () => "failed",
+        cancelledMessage: () => "cancelled",
+        sessionExpiredMessage: () => "expired",
+      });
+
+      const firstStart = runner.start("original", method);
+      if (action === "cancel") {
+        await runner.cancel();
+      } else if (action === "settled cancel") {
+        await runner.cancel({ settleActiveRequest: true });
+      } else {
+        runner.close();
+      }
+      resolveFirstStart();
+      await firstStart;
+
+      expect(runningSession).toBeNull();
+      expect(request).toHaveBeenCalledWith(
+        "wizard.cancel",
+        { sessionId: firstSessionId },
+        { timeoutMs: 30_000 },
+      );
+      await expect(runner.start("replacement", method)).resolves.toEqual({ startMethod: method });
+      expect(runner.state).toEqual({ phase: "done", authChoice: "replacement" });
+    },
+  );
+
+  it.each([
+    ["openclaw.setup.auth.start", false],
+    ["openclaw.setup.prepare.start", false],
+    ["openclaw.setup.auth.start", true],
+    ["openclaw.setup.prepare.start", true],
+  ] as const)(
+    "retains late %s responses after the local deadline (terminal: %s)",
+    async (method, terminal) => {
+      vi.useFakeTimers();
+      try {
+        let runningSession: string | null = null;
+        let firstSessionId = "";
+        let resolveFirstStart: () => void = () => {
+          throw new Error("the first setup request did not start");
+        };
+        let startCount = 0;
+        const request = vi.fn(
+          async (
+            requestMethod: string,
+            params?: { sessionId?: string },
+            options?: { signal?: AbortSignal; timeoutMs?: number | null },
+          ) => {
+            if (requestMethod === method) {
+              const sessionId = params?.sessionId;
+              if (!sessionId) {
+                throw new Error("missing setup session");
+              }
+              if (startCount++ === 0) {
+                firstSessionId = sessionId;
+                return await new Promise((resolve, reject) => {
+                  options?.signal?.addEventListener("abort", () => reject(new Error("aborted")), {
+                    once: true,
+                  });
+                  if (typeof options?.timeoutMs === "number") {
+                    setTimeout(
+                      () => reject(new Error("Gateway retired the timed-out request")),
+                      options.timeoutMs,
+                    );
+                  }
+                  resolveFirstStart = () => {
+                    if (!terminal) {
+                      runningSession = sessionId;
+                    }
+                    resolve({ sessionId, done: terminal, status: terminal ? "done" : "running" });
+                  };
+                });
+              }
+              if (runningSession) {
+                throw new Error("wizard already running");
+              }
+              return { sessionId, done: true, status: "done" };
+            }
+            if (requestMethod === "wizard.cancel") {
+              if (runningSession !== params?.sessionId) {
+                throw new Error("wizard not found");
+              }
+              runningSession = null;
+              return { status: "cancelled" };
+            }
+            throw new Error(`unexpected request ${requestMethod}`);
+          },
+        );
+        const client = { request } as unknown as GatewayBrowserClient;
+        const runner = new ModelSetupWizardRunner({
+          getClient: () => client,
+          getAgentId: () => null,
+          onChange: () => undefined,
+          requestFailedMessage: () => "failed",
+          cancelledMessage: () => "cancelled",
+          sessionExpiredMessage: () => "expired",
+        });
+
+        const timedOutStart = runner.start("original", method);
+        await vi.advanceTimersByTimeAsync(30_000);
+        await timedOutStart;
+        expect(runner.state).toEqual({
+          phase: "error",
+          message: `gateway request timed out after 30000ms: ${method}`,
+        });
+
+        resolveFirstStart();
+        await vi.runAllTimersAsync();
+        expect(runningSession).toBeNull();
+        const cancelCalls = request.mock.calls.filter(
+          ([requestMethod]) => requestMethod === "wizard.cancel",
+        );
+        const lateCancelCalls = cancelCalls.filter(
+          ([, params]) => params?.sessionId === firstSessionId,
+        );
+        expect(lateCancelCalls).toHaveLength(terminal ? 1 : 2);
+
+        await runner.cancel();
+        await expect(runner.start("replacement", method)).resolves.toEqual({ startMethod: method });
+        expect(runner.state).toEqual({ phase: "done", authChoice: "replacement" });
+      } finally {
+        vi.useRealTimers();
+      }
+    },
+  );
+
+  it("cleans the original Gateway session without disturbing a replacement connection", async () => {
+    let originalSessionId = "";
+    let resolveOriginalStart: () => void = () => {
+      throw new Error("the original setup request did not start");
+    };
+    const originalRequest = vi.fn(
+      async (
+        method: string,
+        params?: { sessionId?: string },
+        options?: { signal?: AbortSignal },
+      ) => {
+        if (method === "openclaw.setup.auth.start") {
+          originalSessionId = params?.sessionId ?? "";
+          return await new Promise((resolve, reject) => {
+            options?.signal?.addEventListener("abort", () => reject(new Error("aborted")), {
+              once: true,
+            });
+            resolveOriginalStart = () =>
+              resolve({ sessionId: originalSessionId, done: false, status: "running" });
+          });
+        }
+        return { status: "cancelled" };
+      },
+    );
+    const replacementRequest = vi.fn(async (method: string, params?: { sessionId?: string }) => {
+      if (method === "openclaw.setup.auth.start") {
+        return { sessionId: params?.sessionId, done: false, status: "running" };
+      }
+      if (method === "wizard.next") {
+        return {
+          done: false,
+          status: "running",
+          step: { id: "replacement", type: "text", message: "Replacement setup" },
+        };
+      }
+      throw new Error(`unexpected replacement request ${method}`);
+    });
+    const originalClient = { request: originalRequest } as unknown as GatewayBrowserClient;
+    const replacementClient = { request: replacementRequest } as unknown as GatewayBrowserClient;
+    let currentClient = originalClient;
+    const runner = new ModelSetupWizardRunner({
+      getClient: () => currentClient,
+      getAgentId: () => null,
+      onChange: () => undefined,
+      requestFailedMessage: () => "failed",
+      cancelledMessage: () => "cancelled",
+      sessionExpiredMessage: () => "expired",
+    });
+
+    const originalStart = runner.start("original");
+    runner.close();
+    currentClient = replacementClient;
+    await runner.start("replacement");
+    resolveOriginalStart();
+    await originalStart;
+
+    expect(originalRequest).toHaveBeenCalledWith(
+      "wizard.cancel",
+      { sessionId: originalSessionId },
+      { timeoutMs: 30_000 },
+    );
+    expect(replacementRequest.mock.calls.some(([method]) => method === "wizard.cancel")).toBe(
+      false,
+    );
+    expect(runner.state).toMatchObject({ phase: "step", authChoice: "replacement" });
+  });
+
+  it.each(["openclaw.setup.auth.start", "openclaw.setup.prepare.start"] as const)(
+    "does not cancel a terminal %s result after its wizard closes",
+    async (method) => {
+      let resolveStart: () => void = () => {
+        throw new Error("the setup request did not start");
+      };
+      const request = vi.fn(async (requestMethod: string) => {
+        if (requestMethod === method) {
+          return await new Promise((resolve) => {
+            resolveStart = () => resolve({ done: true, status: "done" });
+          });
+        }
+        throw new Error(`unexpected request ${requestMethod}`);
+      });
+      const client = { request } as unknown as GatewayBrowserClient;
+      const runner = new ModelSetupWizardRunner({
+        getClient: () => client,
+        getAgentId: () => null,
+        onChange: () => undefined,
+        requestFailedMessage: () => "failed",
+        cancelledMessage: () => "cancelled",
+        sessionExpiredMessage: () => "expired",
+      });
+
+      const start = runner.start("original", method);
+      runner.close();
+      resolveStart();
+      await start;
+
+      expect(request.mock.calls.map(([requestMethod]) => requestMethod)).toEqual([method]);
+      expect(runner.state).toEqual({ phase: "idle" });
+    },
+  );
+
   it("clears an expired session and abort without cancelling or replaying the answer", async () => {
     let nextCount = 0;
     let answerSignal: AbortSignal | undefined;
diff --git a/ui/src/pages/model-setup/wizard-runner.ts b/ui/src/pages/model-setup/wizard-runner.ts
index 718d3528891f..df2becb2c8e6 100644
--- a/ui/src/pages/model-setup/wizard-runner.ts
+++ b/ui/src/pages/model-setup/wizard-runner.ts
@@ -57,16 +57,21 @@ export class ModelSetupWizardRunner {
     this.setState({ phase: "starting", authChoice });
     try {
       const agentId = this.options.getAgentId();
-      const started = await client.request<SystemAgentSetupAuthStartResult>(
+      const request = client.request<SystemAgentSetupAuthStartResult>(
         startMethod,
         {
           sessionId,
           authChoice,
           ...(agentId ? { agentId } : {}),
         },
-        { timeoutMs: MODEL_SETUP_AUTH_START_TIMEOUT_MS, signal: abortController.signal },
+        { timeoutMs: null },
       );
+      const started = await this.awaitWizardStart(client, request, sessionId, startMethod);
       if (generation !== this.generation) {
+        if (!started.done) {
+          // Admission can finish after cancellation; release only this generation's original session.
+          await this.cancelSession(client, sessionId);
+        }
         return null;
       }
       if (started.done) {
@@ -108,15 +113,7 @@ export class ModelSetupWizardRunner {
     if (!client || !sessionId) {
       return;
     }
-    try {
-      await client.request(
-        "wizard.cancel",
-        { sessionId },
-        { timeoutMs: MODEL_SETUP_AUTH_START_TIMEOUT_MS },
-      );
-    } catch {
-      // The gateway may have already completed or purged the session.
-    }
+    await this.cancelSession(client, sessionId);
   }
 
   close(): void {
@@ -133,6 +130,40 @@ export class ModelSetupWizardRunner {
     this.setState({ phase: "error", message });
   }
 
+  private async awaitWizardStart(
+    client: GatewayBrowserClient,
+    request: Promise<SystemAgentSetupAuthStartResult>,
+    sessionId: string,
+    startMethod: ModelSetupWizardStartMethod,
+  ): Promise<SystemAgentSetupAuthStartResult> {
+    let timedOut = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    // Gateway request abort/deadline retirement discards the late session needed for cleanup.
+    const retainedRequest = request.then(async (result) => {
+      if (timedOut && !result.done) {
+        await this.cancelSession(client, sessionId);
+      }
+      return result;
+    });
+    try {
+      return await Promise.race([
+        retainedRequest,
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(() => {
+            timedOut = true;
+            reject(
+              new Error(
+                `gateway request timed out after ${MODEL_SETUP_AUTH_START_TIMEOUT_MS}ms: ${startMethod}`,
+              ),
+            );
+          }, MODEL_SETUP_AUTH_START_TIMEOUT_MS);
+        }),
+      ]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
   private async requestNext(
     authChoice: string,
     answer: { stepId: string; value?: unknown } | undefined,
@@ -202,11 +233,7 @@ export class ModelSetupWizardRunner {
     this.abortController = null;
     const sessionExpired = isWizardNotFoundError(error);
     if (!sessionExpired && client && sessionId) {
-      void client
-        .request("wizard.cancel", { sessionId }, { timeoutMs: MODEL_SETUP_AUTH_START_TIMEOUT_MS })
-        .catch(() => {
-          // The failed request may have already completed or purged the session.
-        });
+      void this.cancelSession(client, sessionId);
     }
     const message = sessionExpired
       ? this.options.sessionExpiredMessage()
@@ -214,6 +241,18 @@ export class ModelSetupWizardRunner {
     this.setState({ phase: "error", message });
   }
 
+  private async cancelSession(client: GatewayBrowserClient, sessionId: string): Promise<void> {
+    try {
+      await client.request(
+        "wizard.cancel",
+        { sessionId },
+        { timeoutMs: MODEL_SETUP_AUTH_START_TIMEOUT_MS },
+      );
+    } catch {
+      // The Gateway may already have completed or purged the session.
+    }
+  }
+
   private setState(state: ModelSetupWizardState): void {
     this.currentState = state;
     this.options.onChange(state);

From 680001bec4d44d671eae408b18b8b89b905bd15e Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 15:35:31 -0700
Subject: [PATCH 113/124] fix(gateway): fix plugin metadata lifecycle staleness
 in auth-bypass cache and config reload (#127664)

The gateway HTTP auth-bypass path cache was keyed only by config object
identity, so replacing a channel plugin's declared bypass contract while
config identity stayed stable preserved obsolete unauthenticated HTTP
routes. It now clears on plugin metadata lifecycle resets alongside every
other plugin-derived process memo.

notifyPluginMetadataChanged cleared the process plugin metadata snapshot
slot, but when config bytes were unchanged the config-reload diff took its
early no-op return and skipped both plugin reload and republishing, leaving
the snapshot slot empty so configless readers cold-scanned repeatedly. An
unchanged-bytes metadata signal now forces a plugin-reload plan so the
runtime generation republishes.
---
 src/gateway/config-reload.test.ts           | 48 ++++++++++++
 src/gateway/config-reload.ts                | 36 ++++++++-
 src/gateway/server-http-plugin-auth.test.ts | 86 +++++++++++++++++++++
 src/gateway/server-http-plugin-auth.ts      | 23 ++++--
 4 files changed, 184 insertions(+), 9 deletions(-)
 create mode 100644 src/gateway/server-http-plugin-auth.test.ts

diff --git a/src/gateway/config-reload.test.ts b/src/gateway/config-reload.test.ts
index 362c8c42b6ad..cbf549334333 100644
--- a/src/gateway/config-reload.test.ts
+++ b/src/gateway/config-reload.test.ts
@@ -4507,6 +4507,54 @@ describe("startGatewayConfigReloader", () => {
     await harness.reloader.stop();
   });
 
+  it("forces a plugin reload when signaled metadata leaves config and install records identical", async () => {
+    const activeConfig: OpenClawConfig = {
+      gateway: { reload: {} },
+    };
+    const installRecords = {
+      brave: {
+        source: "npm",
+        spec: "@openclaw/brave",
+        installPath: "/tmp/openclaw/plugins/brave",
+      },
+    } satisfies Record<string, PluginInstallRecord>;
+    const readSnapshot = vi.fn(async () =>
+      makeSnapshot({
+        sourceConfig: activeConfig,
+        runtimeConfig: activeConfig,
+        config: activeConfig,
+        hash: "unchanged-config",
+      }),
+    );
+    const readPluginInstallRecords = vi.fn(async () => ({ ...installRecords }));
+    const harness = createReloaderHarness(readSnapshot, {
+      initialConfig: activeConfig,
+      initialCompareConfig: activeConfig,
+      initialPluginInstallRecords: installRecords,
+      readPluginInstallRecords,
+    });
+
+    harness.reloader.notifyPluginMetadataChanged();
+    await vi.runOnlyPendingTimersAsync();
+
+    expect(harness.onRestart).not.toHaveBeenCalled();
+    const [plan, nextConfig] = getOnlyHotReloadCall(harness);
+    expect(plan.changedPaths).toEqual([]);
+    expect(plan.restartGateway).toBe(false);
+    expect(plan.reloadPlugins).toBe(true);
+    expect(plan.disposeMcpRuntimes).toBe(true);
+    expect(nextConfig).toBe(activeConfig);
+
+    // The refresh is consumed by the committed reload: a later watcher echo of
+    // identical bytes must not replace the plugin runtime generation again.
+    harness.watcher.emit("change");
+    await vi.runOnlyPendingTimersAsync();
+    expect(harness.onHotReload).toHaveBeenCalledTimes(1);
+    expect(harness.onRestart).not.toHaveBeenCalled();
+
+    await harness.reloader.stop();
+  });
+
   it("keeps external plugin policy-only writes on the hot reload path", async () => {
     const previousConfig: OpenClawConfig = {
       gateway: { reload: {} },
diff --git a/src/gateway/config-reload.ts b/src/gateway/config-reload.ts
index 0ea1c6939b4f..223b2df250e6 100644
--- a/src/gateway/config-reload.ts
+++ b/src/gateway/config-reload.ts
@@ -265,6 +265,11 @@ export function startGatewayConfigReloader(opts: {
   const activeReloads = new Set<Promise<void>>();
   let missingConfigRetries = 0;
   let configWriteEpoch = 0;
+  // Signaled metadata changes clear the process snapshot slot before the diff
+  // pass runs; the counters keep that pass honest when config bytes are
+  // unchanged, and stay pending until a plugin reload or restart commits.
+  let pluginMetadataRefreshRequests = 0;
+  let pluginMetadataRefreshApplied = 0;
   let pendingInProcessConfig: InProcessConfigCandidate | null = null;
   let activeInProcessConfig: InProcessConfigCandidate | null = null;
   let watcherIntentCandidate: InProcessConfigCandidate | null = null;
@@ -644,7 +649,16 @@ export function startGatewayConfigReloader(opts: {
       }
       notifyCommitted();
     };
-    if (changedPaths.length === 0) {
+    // A signaled metadata change emptied the process snapshot slot. An
+    // unchanged config diff must still replace the plugin runtime generation so
+    // the slot republishes instead of leaving configless readers cold-scanning
+    // against a registry that diverged from the live runtime owners.
+    const pluginMetadataRefreshToken = pluginMetadataRefreshRequests;
+    const forcePluginMetadataReload = pluginMetadataRefreshToken !== pluginMetadataRefreshApplied;
+    const markPluginMetadataRefreshApplied = () => {
+      pluginMetadataRefreshApplied = pluginMetadataRefreshToken;
+    };
+    if (changedPaths.length === 0 && !forcePluginMetadataReload) {
       let publishedSource: { rollback: () => Promise<void>; commit?: () => void } | undefined;
       let publishedSourceRollback: (() => Promise<void>) | undefined;
       let publishedSourceRolledBack = false;
@@ -681,7 +695,11 @@ export function startGatewayConfigReloader(opts: {
     }
 
     const followUp = resolveConfigWriteFollowUp(afterWrite);
-    opts.log.info(`config change detected; evaluating reload (${changedPaths.join(", ")})`);
+    opts.log.info(
+      changedPaths.length > 0
+        ? `config change detected; evaluating reload (${changedPaths.join(", ")})`
+        : "plugin metadata changed with identical config; replacing plugin runtime generation",
+    );
     if (followUp.mode === "none") {
       opts.log.info(`config reload skipped by writer intent (${followUp.reason})`);
       await commitReloadBaseline({ runtimeApplied: false });
@@ -692,6 +710,12 @@ export function startGatewayConfigReloader(opts: {
       forceChangedPaths: pluginInstallWholeRecordPaths,
       candidateConfig: nextConfig,
     });
+    if (forcePluginMetadataReload && !plan.restartGateway && !plan.reloadPlugins) {
+      // Mirror the `plugins.*` hot rule pairing: a replaced plugin registry
+      // also invalidates MCP runtimes assembled from the previous generation.
+      plan.reloadPlugins = true;
+      plan.disposeMcpRuntimes = true;
+    }
     if (nextSettings.mode === "off") {
       opts.log.info("config reload disabled (gateway.reload.mode=off)");
       await commitReloadBaseline({ runtimeApplied: false });
@@ -716,12 +740,15 @@ export function startGatewayConfigReloader(opts: {
       await opts.onConfigChange?.(restartPlan, nextConfig);
       await prepareRestart(restartPlan, nextConfig, ownership, nextSourceConfig);
       await commitReloadBaseline();
+      // The accepted restart owns snapshot republication at next startup.
+      markPluginMetadataRefreshApplied();
       return;
     }
     if (plan.restartGateway) {
       await opts.onConfigChange?.(plan, nextConfig);
       await prepareRestart(plan, nextConfig, ownership, nextSourceConfig);
       await commitReloadBaseline();
+      markPluginMetadataRefreshApplied();
       return;
     }
 
@@ -735,6 +762,10 @@ export function startGatewayConfigReloader(opts: {
     assertCurrent();
     await appliedRevision.apply(plan, nextConfig, nextConfigRevisionHash);
     await commitReloadBaseline();
+    if (plan.reloadPlugins) {
+      // The committed reload republished the metadata snapshot generation.
+      markPluginMetadataRefreshApplied();
+    }
   };
 
   const promoteAcceptedSnapshot = async (snapshot: ConfigFileSnapshot, reason: string) => {
@@ -1271,6 +1302,7 @@ export function startGatewayConfigReloader(opts: {
     notifyPluginMetadataChanged: () => {
       // The signal carries a metadata change while config bytes stay identical.
       // Clear both metadata and config-echo caches before scheduling the shared diff path.
+      pluginMetadataRefreshRequests += 1;
       clearLoadInstalledPluginIndexInstallRecordsCache();
       clearPluginMetadataLifecycleCaches();
       startupInternalWriteHash = null;
diff --git a/src/gateway/server-http-plugin-auth.test.ts b/src/gateway/server-http-plugin-auth.test.ts
new file mode 100644
index 000000000000..adc67f3ef0e4
--- /dev/null
+++ b/src/gateway/server-http-plugin-auth.test.ts
@@ -0,0 +1,86 @@
+// Covers plugin gateway auth bypass caching across metadata lifecycle resets.
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig } from "../config/types.openclaw.js";
+import { clearPluginMetadataLifecycleCaches } from "../plugins/plugin-metadata-lifecycle.js";
+import { getCachedPluginGatewayAuthBypassPaths } from "./server-http-plugin-auth.js";
+
+const resolveBypassPaths = vi.hoisted(() =>
+  vi.fn<(params: { channelId: string; cfg: OpenClawConfig }) => Promise<string[]>>(),
+);
+
+vi.mock("../channels/plugins/gateway-auth-bypass.js", () => ({
+  resolveBundledChannelGatewayAuthBypassPaths: resolveBypassPaths,
+}));
+
+describe("getCachedPluginGatewayAuthBypassPaths", () => {
+  beforeEach(() => {
+    resolveBypassPaths.mockReset();
+    clearPluginMetadataLifecycleCaches();
+  });
+
+  it("caches resolved bypass paths per config identity", async () => {
+    const config: OpenClawConfig = { channels: { telegram: {} } };
+    resolveBypassPaths.mockResolvedValue(["/telegram/webhook"]);
+
+    await expect(getCachedPluginGatewayAuthBypassPaths(config)).resolves.toEqual(
+      new Set(["/telegram/webhook"]),
+    );
+    await getCachedPluginGatewayAuthBypassPaths(config);
+    expect(resolveBypassPaths).toHaveBeenCalledTimes(1);
+  });
+
+  it("drops cached bypass paths on a metadata lifecycle reset despite stable config identity", async () => {
+    const config: OpenClawConfig = { channels: { telegram: {} } };
+    resolveBypassPaths.mockResolvedValueOnce(["/telegram/old-bypass"]);
+    await expect(getCachedPluginGatewayAuthBypassPaths(config)).resolves.toEqual(
+      new Set(["/telegram/old-bypass"]),
+    );
+
+    // Same config object, replaced plugin contract: the reset must invalidate,
+    // or the predecessor's unauthenticated paths keep bypassing gateway auth.
+    clearPluginMetadataLifecycleCaches();
+    resolveBypassPaths.mockResolvedValueOnce(["/telegram/new-bypass"]);
+
+    await expect(getCachedPluginGatewayAuthBypassPaths(config)).resolves.toEqual(
+      new Set(["/telegram/new-bypass"]),
+    );
+  });
+
+  it("retries after a failed resolution instead of caching the rejection", async () => {
+    const config: OpenClawConfig = { channels: { telegram: {} } };
+    resolveBypassPaths.mockRejectedValueOnce(new Error("resolution failed"));
+    await expect(getCachedPluginGatewayAuthBypassPaths(config)).rejects.toThrow(
+      "resolution failed",
+    );
+
+    resolveBypassPaths.mockResolvedValueOnce(["/telegram/webhook"]);
+    await expect(getCachedPluginGatewayAuthBypassPaths(config)).resolves.toEqual(
+      new Set(["/telegram/webhook"]),
+    );
+  });
+
+  it("keeps the fresh generation cached when a stale failed resolution settles late", async () => {
+    const config: OpenClawConfig = { channels: { telegram: {} } };
+    let rejectStale: (error: Error) => void = () => {};
+    resolveBypassPaths.mockReturnValueOnce(
+      new Promise<string[]>((_resolve, reject) => {
+        rejectStale = reject;
+      }),
+    );
+    const stale = getCachedPluginGatewayAuthBypassPaths(config);
+
+    clearPluginMetadataLifecycleCaches();
+    resolveBypassPaths.mockResolvedValue(["/telegram/webhook"]);
+    await expect(getCachedPluginGatewayAuthBypassPaths(config)).resolves.toEqual(
+      new Set(["/telegram/webhook"]),
+    );
+
+    rejectStale(new Error("stale plugin generation failed"));
+    await expect(stale).rejects.toThrow("stale plugin generation failed");
+
+    // The stale rejection evicts from its own generation only; the fresh entry
+    // must stay cached instead of being re-resolved.
+    await getCachedPluginGatewayAuthBypassPaths(config);
+    expect(resolveBypassPaths).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/src/gateway/server-http-plugin-auth.ts b/src/gateway/server-http-plugin-auth.ts
index a9b5a677d03f..e9bed61a915e 100644
--- a/src/gateway/server-http-plugin-auth.ts
+++ b/src/gateway/server-http-plugin-auth.ts
@@ -1,5 +1,6 @@
 import { resolveBundledChannelGatewayAuthBypassPaths } from "../channels/plugins/gateway-auth-bypass.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
+import { registerPluginMetadataProcessMemoLifecycleClear } from "../plugins/plugin-metadata-lifecycle.js";
 import type { AuthorizedGatewayHttpRequest } from "./http-auth-utils.js";
 import type { PluginNodeCapabilitySurface } from "./plugin-node-capability.js";
 import {
@@ -18,10 +19,15 @@ export type ResolvePluginNodeCapabilityRoute = (
   pathContext: PluginRoutePathContext,
 ) => PluginNodeCapabilitySurface | undefined;
 
-const pluginGatewayAuthBypassPathsCache = new WeakMap<
-  OpenClawConfig,
-  Promise<ReadonlySet<string>>
->();
+// Bypass paths come from plugin-declared artifacts, not config bytes alone. A
+// metadata lifecycle reset can replace that contract while the config object
+// identity stays stable, so the cache must roll to a fresh generation on reset
+// or a replaced channel plugin keeps its predecessor's HTTP auth exceptions.
+let pluginGatewayAuthBypassPathsCache = new WeakMap<OpenClawConfig, Promise<ReadonlySet<string>>>();
+
+registerPluginMetadataProcessMemoLifecycleClear(() => {
+  pluginGatewayAuthBypassPathsCache = new WeakMap();
+});
 
 async function resolvePluginGatewayAuthBypassPaths(
   configSnapshot: OpenClawConfig,
@@ -45,15 +51,18 @@ async function resolvePluginGatewayAuthBypassPaths(
 export function getCachedPluginGatewayAuthBypassPaths(
   configSnapshot: OpenClawConfig,
 ): Promise<ReadonlySet<string>> {
-  const cached = pluginGatewayAuthBypassPathsCache.get(configSnapshot);
+  const cache = pluginGatewayAuthBypassPathsCache;
+  const cached = cache.get(configSnapshot);
   if (cached) {
     return cached;
   }
   const resolved = resolvePluginGatewayAuthBypassPaths(configSnapshot).catch((error: unknown) => {
-    pluginGatewayAuthBypassPathsCache.delete(configSnapshot);
+    // Evict from the owning generation only; a stale failure settling after a
+    // lifecycle reset must not drop a freshly cached entry.
+    cache.delete(configSnapshot);
     throw error;
   });
-  pluginGatewayAuthBypassPathsCache.set(configSnapshot, resolved);
+  cache.set(configSnapshot, resolved);
   return resolved;
 }
 

From a5e9b3189d0acd769868951656e5fc6ff1647ba5 Mon Sep 17 00:00:00 2001
From: Jesse Merhi <79823012+jesse-merhi@users.noreply.github.com>
Date: Sat, 22 Aug 2026 08:36:26 +1000
Subject: [PATCH 114/124] fix(ui): keep chat pinned as composer grows (#122985)

Co-authored-by: Jesse Merhi <jesse-merhi@users.noreply.github.com>
---
 ui/src/e2e/chat-flow.streaming.e2e.test.ts    | 77 +++++++++++++++++++
 .../chat/components/chat-composer-dom.ts      | 11 +++
 2 files changed, 88 insertions(+)

diff --git a/ui/src/e2e/chat-flow.streaming.e2e.test.ts b/ui/src/e2e/chat-flow.streaming.e2e.test.ts
index 45f83d6f2de9..d316e8122a88 100644
--- a/ui/src/e2e/chat-flow.streaming.e2e.test.ts
+++ b/ui/src/e2e/chat-flow.streaming.e2e.test.ts
@@ -253,6 +253,83 @@ suite.define(() => {
     }
   });
 
+  it("keeps a bottom-anchored transcript pinned while the composer grows", async () => {
+    const artifactDir = process.env.OPENCLAW_UI_E2E_ARTIFACT_DIR?.trim();
+    const context = await suite.newBrowserContext({
+      locale: "en-US",
+      serviceWorkers: "block",
+      viewport: { height: 900, width: 1280 },
+    });
+    const page = await context.newPage();
+    const baseTs = Date.now() - 100_000;
+    const historyMessages = Array.from({ length: 50 }, (_, index) => ({
+      content: [
+        {
+          text: `Composer resize history ${index}\n${"extra transcript line\n".repeat(4)}`,
+          type: "text",
+        },
+      ],
+      role: index % 2 === 0 ? "assistant" : "user",
+      timestamp: baseTs + index,
+    }));
+    await installMockGateway(page, { historyMessages });
+
+    try {
+      await page.goto(`${suite.server.baseUrl}chat`);
+      await page.getByText("Composer resize history 49").waitFor({ timeout: 10_000 });
+      await expect
+        .poll(() => chatThreadDistanceFromBottom(page), { timeout: 10_000 })
+        .toBeLessThanOrEqual(CHAT_TRANSCRIPT_END_THRESHOLD_PX);
+      await waitForChatScrollIdle(page);
+
+      const composer = page.locator(".agent-chat__composer-combobox textarea");
+      for (let line = 1; line <= 8; line += 1) {
+        await composer.fill(
+          Array.from({ length: line }, (_, index) => `Growing composer line ${index + 1}`).join(
+            "\n",
+          ),
+        );
+        await waitForChatScrollIdle(page);
+        expect(
+          await chatThreadDistanceFromBottom(page),
+          `composer line count ${line}`,
+        ).toBeLessThanOrEqual(CHAT_TRANSCRIPT_END_THRESHOLD_PX);
+      }
+      if (artifactDir) {
+        await mkdir(artifactDir, { recursive: true });
+        await page.screenshot({
+          fullPage: true,
+          path: path.join(artifactDir, "composer-resize-pinned.png"),
+        });
+      }
+
+      await composer.fill("Growing composer line 1");
+      await waitForChatScrollIdle(page);
+      await scrollChatThreadToTop(page);
+      const readingScrollTop = await page
+        .locator(".chat-thread")
+        .evaluate((element) => element.scrollTop);
+      await composer.fill(
+        Array.from({ length: 8 }, (_, index) => `Reading composer line ${index + 1}`).join("\n"),
+      );
+      await waitForChatScrollIdle(page);
+      expect(
+        await page
+          .locator(".chat-thread")
+          .evaluate((element, initial) => Math.abs(element.scrollTop - initial), readingScrollTop),
+      ).toBeLessThanOrEqual(1);
+
+      if (artifactDir) {
+        await page.screenshot({
+          fullPage: true,
+          path: path.join(artifactDir, "composer-resize-manual-scroll.png"),
+        });
+      }
+    } finally {
+      await suite.closeBrowserContext(context);
+    }
+  });
+
   it("renders stable markdown during a streaming chat turn and finalizes the tail", async () => {
     const context = await suite.newBrowserContext({
       locale: "en-US",
diff --git a/ui/src/pages/chat/components/chat-composer-dom.ts b/ui/src/pages/chat/components/chat-composer-dom.ts
index 58088d70f77d..621314e47f02 100644
--- a/ui/src/pages/chat/components/chat-composer-dom.ts
+++ b/ui/src/pages/chat/components/chat-composer-dom.ts
@@ -1,3 +1,5 @@
+import { captureChatSessionScrollPosition } from "../scroll.ts";
+
 const COMPOSER_CHROME_INTERACTIVE_SELECTOR = [
   "a[href]",
   "button",
@@ -126,6 +128,10 @@ function updateTextareaOverflow(el: HTMLTextAreaElement) {
 }
 
 export function adjustTextareaHeight(el: HTMLTextAreaElement) {
+  const thread = el.closest(".chat")?.querySelector<HTMLElement>(".chat-thread") ?? null;
+  const preserveBottomAnchor = thread
+    ? captureChatSessionScrollPosition(thread).anchorToEnd
+    : false;
   // Hide the browser's scrollbar while measuring; restore it only when the
   // final CSS-constrained height actually clips the draft.
   el.style.overflowY = "hidden";
@@ -137,6 +143,11 @@ export function adjustTextareaHeight(el: HTMLTextAreaElement) {
   const maxHeight = pixelMaxHeight ? Number(pixelMaxHeight[1]) : 150;
   el.style.height = `${Math.min(el.scrollHeight, maxHeight)}px`;
   updateTextareaOverflow(el);
+  // Once capped, the textarea can perturb the sibling transcript without
+  // resizing its viewport, so ResizeObserver has no correction to apply.
+  if (thread && preserveBottomAnchor) {
+    thread.scrollTop = thread.scrollHeight;
+  }
 }
 
 export function observeTextareaOverflow(el: HTMLTextAreaElement) {

From 5165fbb4e74067f97e9949202f580ffba641b00b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 15:36:52 -0700
Subject: [PATCH 115/124] refactor(process): supervise Claude node invocations
 (#127475)

* refactor(process): supervise Claude node invocations

* fix(process): preserve exact node invocation environment

* test(telegram): await album reply dispatch deterministically
---
 config/assertion-safety-baseline.txt          |   4 +-
 ...egram-bot.media-group-skip-warning.test.ts |  23 +-
 ...invoke-agent-cli-claude-pipe-error.test.ts |  69 ----
 src/node-host/invoke-agent-cli-claude.test.ts | 182 ++++++---
 src/node-host/invoke-agent-cli-claude.ts      | 350 ++++++++----------
 src/process/decoded-output.ts                 |  11 +-
 .../supervisor/adapters/child-stdin.ts        |  65 ++++
 .../adapters/child.service-lifecycle.test.ts  |   1 +
 src/process/supervisor/adapters/child.test.ts |   4 +-
 src/process/supervisor/adapters/child.ts      |  81 +---
 .../supervisor/service-child-relay-host.ts    | 112 ++----
 src/process/supervisor/supervisor.test.ts     |  54 ++-
 src/process/supervisor/supervisor.ts          |  64 +++-
 src/process/supervisor/types.ts               |  11 +-
 14 files changed, 537 insertions(+), 494 deletions(-)
 delete mode 100644 src/node-host/invoke-agent-cli-claude-pipe-error.test.ts
 create mode 100644 src/process/supervisor/adapters/child-stdin.ts

diff --git a/config/assertion-safety-baseline.txt b/config/assertion-safety-baseline.txt
index c52b4bc7dfc2..fe6e92d7d411 100644
--- a/config/assertion-safety-baseline.txt
+++ b/config/assertion-safety-baseline.txt
@@ -3454,7 +3454,7 @@ src/model-picker/apply-session-model-selection.ts	1
 src/node-host/config.ts	1
 src/node-host/desktop-stream-command.ts	2
 src/node-host/invoke-agent-cli-claude-params.ts	4
-src/node-host/invoke-agent-cli-claude.ts	2
+src/node-host/invoke-agent-cli-claude.ts	1
 src/node-host/invoke-file-commands.ts	1
 src/node-host/invoke-payload.ts	5
 src/node-host/invoke.ts	7
@@ -3706,7 +3706,7 @@ src/process/exec-spawn.ts	4
 src/process/exec.ts	3
 src/process/spawn-secret-input.ts	1
 src/process/spawn-utils.ts	1
-src/process/supervisor/adapters/child.ts	3
+src/process/supervisor/adapters/child.ts	2
 src/process/supervisor/adapters/pty.ts	1
 src/process/terminal-pty.ts	1
 src/process/windows-command.ts	1
diff --git a/extensions/telegram/src/bot.create-telegram-bot.media-group-skip-warning.test.ts b/extensions/telegram/src/bot.create-telegram-bot.media-group-skip-warning.test.ts
index 91e9701c9144..2ade575e4961 100644
--- a/extensions/telegram/src/bot.create-telegram-bot.media-group-skip-warning.test.ts
+++ b/extensions/telegram/src/bot.create-telegram-bot.media-group-skip-warning.test.ts
@@ -1,5 +1,4 @@
 // Telegram tests cover bot.create telegram bot.media group skip warning plugin behavior.
-import { setTimeout as delay } from "node:timers/promises";
 import { coerceErrorMessage } from "openclaw/plugin-sdk/error-runtime";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { telegramBotInfoForTest } from "./bot.create-telegram-bot.test-support.js";
@@ -101,15 +100,19 @@ function resolveFlushTimer(setTimeoutSpy: ReturnType<typeof vi.spyOn>) {
   return flushTimer;
 }
 
-async function waitForBufferedProcessing() {
-  await delay(75);
-}
-
 async function flushChannelPostMediaGroup(setTimeoutSpy: ReturnType<typeof vi.spyOn>) {
+  const replyDispatched = new Promise<void>((resolve) => {
+    const previousReply = replySpy.getMockImplementation();
+    replySpy.mockImplementationOnce(async (...args) => {
+      const result = await previousReply?.(...args);
+      resolve();
+      return result;
+    });
+  });
   const flushTimer = resolveFlushTimer(setTimeoutSpy);
   expect(flushTimer).toBeTypeOf("function");
   await flushTimer?.();
-  await waitForBufferedProcessing();
+  await replyDispatched;
 }
 
 function createChannelPostContext(params: {
@@ -206,7 +209,7 @@ describe("createTelegramBot media-group skip warning (#55216)", () => {
       expect(sendMessageSpy).not.toHaveBeenCalled();
       await flushChannelPostMediaGroup(setTimeoutSpy);
 
-      await vi.waitFor(() => expect(sendMessageSpy).toHaveBeenCalledTimes(1));
+      expect(sendMessageSpy).toHaveBeenCalledTimes(1);
       expect(sendMessageSpy).toHaveBeenCalledWith(
         CHANNEL_ID,
         expect.stringContaining("1 of 2 images"),
@@ -219,7 +222,7 @@ describe("createTelegramBot media-group skip warning (#55216)", () => {
       );
       const warningText = String(sendMessageSpy.mock.calls[0]?.[1]);
       expect(warningText).toContain("1 could not be fetched and was skipped");
-      await vi.waitFor(() => expect(replySpy).toHaveBeenCalled());
+      expect(replySpy).toHaveBeenCalled();
       expect(replySpy.mock.calls[0]?.[0]?.media).toEqual([
         expect.objectContaining({ path: "/tmp/p1.jpg", contentType: "image/png" }),
         expect.objectContaining({ kind: "image" }),
@@ -246,7 +249,7 @@ describe("createTelegramBot media-group skip warning (#55216)", () => {
       });
       await flushChannelPostMediaGroup(setTimeoutSpy);
 
-      await vi.waitFor(() => expect(sendMessageSpy).toHaveBeenCalledTimes(1));
+      expect(sendMessageSpy).toHaveBeenCalledTimes(1);
       const warningText = String(sendMessageSpy.mock.calls[0]?.[1]);
       expect(warningText).toContain("0 of 2 images");
       expect(warningText).toContain("2 could not be fetched and were skipped");
@@ -281,7 +284,7 @@ describe("createTelegramBot media-group skip warning (#55216)", () => {
       });
       await flushChannelPostMediaGroup(setTimeoutSpy);
 
-      await vi.waitFor(() => expect(sendMessageSpy).toHaveBeenCalledTimes(1));
+      expect(sendMessageSpy).toHaveBeenCalledTimes(1);
       const warningText = String(sendMessageSpy.mock.calls[0]?.[1]);
       expect(warningText).toContain("1 of 3 images");
       expect(warningText).toContain("2 could not be fetched and were skipped");
diff --git a/src/node-host/invoke-agent-cli-claude-pipe-error.test.ts b/src/node-host/invoke-agent-cli-claude-pipe-error.test.ts
deleted file mode 100644
index f4167ac021ab..000000000000
--- a/src/node-host/invoke-agent-cli-claude-pipe-error.test.ts
+++ /dev/null
@@ -1,69 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-const spawnMock = vi.hoisted(() => vi.fn());
-
-vi.mock("node:child_process", () => ({
-  spawn: spawnMock,
-}));
-
-import type { NodeHostClient } from "./client.js";
-import type { NodeInvokeRequestPayload } from "./invoke.js";
-
-function frame(params: unknown): NodeInvokeRequestPayload {
-  return {
-    id: "invoke-pipe-error",
-    nodeId: "node-pipe-error",
-    command: "agent.cli.claude.run.v1",
-    paramsJSON: JSON.stringify(params),
-  };
-}
-
-function client(): NodeHostClient {
-  return {
-    async request<T = Record<string, unknown>>() {
-      return {} as T;
-    },
-  };
-}
-
-describe("Claude CLI node command pipe errors", () => {
-  let realChild: import("node:child_process").ChildProcessWithoutNullStreams | undefined;
-
-  afterEach(() => {
-    if (realChild && !realChild.killed) {
-      realChild.kill("SIGKILL");
-    }
-    realChild = undefined;
-    spawnMock.mockReset();
-    vi.resetModules();
-  });
-
-  it("guards real child stdout/stderr pipe error events", async () => {
-    const childProcess =
-      await vi.importActual<typeof import("node:child_process")>("node:child_process");
-    realChild = childProcess.spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], {
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-    spawnMock.mockReturnValueOnce(realChild as never);
-    const { runClaudeCliNodeCommand } = await import("./invoke-agent-cli-claude.js");
-
-    const request = { argv: ["-p"], idleTimeoutMs: 100, timeoutMs: 5_000 };
-
-    const run = runClaudeCliNodeCommand({
-      client: client(),
-      frame: frame(request),
-      request,
-      argv: [process.execPath, ...request.argv],
-      cwd: undefined,
-      env: process.env as Record<string, string>,
-      timeoutMs: request.timeoutMs,
-    });
-
-    expect(() => realChild?.stdout.emit("error", new Error("stdout pipe failure"))).not.toThrow();
-    expect(() => realChild?.stderr.emit("error", new Error("stderr pipe failure"))).not.toThrow();
-    realChild.kill("SIGKILL");
-
-    await expect(run).resolves.toMatchObject({ success: false });
-    expect(spawnMock).toHaveBeenCalledOnce();
-  });
-});
diff --git a/src/node-host/invoke-agent-cli-claude.test.ts b/src/node-host/invoke-agent-cli-claude.test.ts
index 545e99c23ab3..91ac8d1b2d33 100644
--- a/src/node-host/invoke-agent-cli-claude.test.ts
+++ b/src/node-host/invoke-agent-cli-claude.test.ts
@@ -2,6 +2,7 @@ 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 { withEnvAsync } from "../test-utils/env.js";
 import type { NodeHostClient } from "./client.js";
 import { decodeClaudeCliNodeRunParams } from "./invoke-agent-cli-claude-params.js";
 import { runClaudeCliNodeCommand } from "./invoke-agent-cli-claude.js";
@@ -41,6 +42,23 @@ async function executableScript(source: string): Promise<string> {
   return file;
 }
 
+function runCommand(
+  executable: string,
+  request: Parameters<typeof runClaudeCliNodeCommand>[0]["request"],
+  overrides: Partial<Parameters<typeof runClaudeCliNodeCommand>[0]> = {},
+) {
+  return runClaudeCliNodeCommand({
+    client: client([]),
+    frame: frame(request),
+    request,
+    argv: [executable, ...request.argv],
+    cwd: undefined,
+    env: process.env as Record<string, string>,
+    timeoutMs: request.timeoutMs,
+    ...overrides,
+  });
+}
+
 describe("Claude CLI node command", () => {
   it.each([
     { argv: ["--unknown"], error: "unsupported Claude CLI argument" },
@@ -369,15 +387,7 @@ process.stdin.on("end", () => {
       idleTimeoutMs: 1_000,
       timeoutMs: 5_000,
     };
-    const result = await runClaudeCliNodeCommand({
-      client: client(calls),
-      frame: frame(request),
-      request,
-      argv: [executable, ...request.argv],
-      cwd: undefined,
-      env: process.env as Record<string, string>,
-      timeoutMs: request.timeoutMs,
-    });
+    const result = await runCommand(executable, request, { client: client(calls) });
 
     const progress = calls
       .filter((call) => call.method === "node.invoke.progress")
@@ -393,6 +403,47 @@ process.stdin.on("end", () => {
     await expect(fs.stat(promptPath ?? "")).rejects.toThrow();
   });
 
+  it.runIf(process.platform !== "win32")(
+    "retains the prompt for an authoritative descendant without delaying the root result",
+    async () => {
+      const markerDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-node-claude-prompt-"));
+      tempDirs.push(markerDir);
+      const marker = path.join(markerDir, "descendant-read");
+      const executable = await executableScript(`
+const { spawn } = require("node:child_process");
+const prompt = process.argv[process.argv.indexOf("--append-system-prompt-file") + 1];
+const child = spawn(process.execPath, ["-e",
+  "setTimeout(() => require('node:fs').writeFileSync(" +
+  JSON.stringify(${JSON.stringify(marker)}) + ", require('node:fs').readFileSync(" +
+  JSON.stringify(prompt) + ", 'utf8')), 300)"
+], { stdio: ["ignore", "ignore", "ignore", 3] });
+child.unref();
+process.stdout.write(JSON.stringify({ type: "result", result: prompt }) + "\\n");`);
+      await withEnvAsync({ OPENCLAW_SERVICE_MARKER: "openclaw" }, async () => {
+        const calls: Array<{ method: string; params: unknown }> = [];
+        const request = {
+          argv: ["-p"],
+          systemPrompt: "descendant-owned prompt",
+          idleTimeoutMs: 2_000,
+          timeoutMs: 5_000,
+        };
+        const result = await runCommand(executable, request, { client: client(calls) });
+        const output = calls
+          .filter((call) => call.method === "node.invoke.progress")
+          .map((call) => (call.params as { chunk: string }).chunk)
+          .join("");
+        const promptPath = (JSON.parse(output) as { result: string }).result;
+
+        expect(result).toMatchObject({ exitCode: 0, success: true });
+        await expect(fs.readFile(promptPath, "utf8")).resolves.toBe("descendant-owned prompt");
+        await vi.waitFor(async () => {
+          expect(await fs.readFile(marker, "utf8")).toBe("descendant-owned prompt");
+          await expect(fs.stat(promptPath)).rejects.toThrow();
+        });
+      });
+    },
+  );
+
   it.each([
     {
       descriptorEnv: "CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR",
@@ -417,12 +468,8 @@ process.stdout.write(JSON.stringify({
 }) + "\\n");`);
       const request = { argv: ["-p"], idleTimeoutMs: 1_000, timeoutMs: 5_000 };
       const calls: Array<{ method: string; params: unknown }> = [];
-      const result = await runClaudeCliNodeCommand({
+      const result = await runCommand(executable, request, {
         client: client(calls),
-        frame: frame(request),
-        request,
-        argv: [executable, ...request.argv],
-        cwd: undefined,
         env: {
           ...process.env,
           [descriptorEnv]: "3",
@@ -431,7 +478,6 @@ process.stdout.write(JSON.stringify({
           fd: 3,
           createData: () => Buffer.from("selected-node-secret"),
         },
-        timeoutMs: request.timeoutMs,
       });
 
       const progress = calls
@@ -457,19 +503,13 @@ function writeChunk() {
   }
   process.stdout.write("\\n" + JSON.stringify({ type: "result", session_id: "tail-session", result: "done" }) + "\\n", () => process.stderr.write("late failure diagnostic"));
 }
-writeChunk();`,
+process.stdout.write(Buffer.concat([
+  Buffer.alloc(199_997, 120), Buffer.from([0xe2, 0x82]), Buffer.from("A\\n")
+]), writeChunk);`,
     );
     const calls: Array<{ method: string; params: unknown }> = [];
     const request = { argv: ["-p"], idleTimeoutMs: 1_000, timeoutMs: 5_000 };
-    const result = await runClaudeCliNodeCommand({
-      client: client(calls),
-      frame: frame(request),
-      request,
-      argv: [executable, ...request.argv],
-      cwd: undefined,
-      env: process.env as Record<string, string>,
-      timeoutMs: request.timeoutMs,
-    });
+    const result = await runCommand(executable, request, { client: client(calls) });
     const progressBytes = calls
       .filter((call) => call.method === "node.invoke.progress")
       .reduce((sum, call) => sum + Buffer.byteLength((call.params as { chunk: string }).chunk), 0);
@@ -478,6 +518,7 @@ writeChunk();`,
       .filter((call) => call.method === "node.invoke.progress")
       .map((call) => (call.params as { chunk: string }).chunk)
       .join("");
+    expect(progress.startsWith(`${"x".repeat(199_997)}�A`)).toBe(true);
     // OUTPUT_CAP_BYTES + TERMINAL_EVENT_MAX_BYTES from invoke-agent-cli-claude.ts.
     expect(progressBytes).toBeLessThanOrEqual(200_000 + 1024 * 1024);
     expect(progress).toContain('"session_id":"tail-session"');
@@ -491,26 +532,88 @@ writeChunk();`,
     ).toBeLessThanOrEqual(2);
   });
 
+  it.each([
+    {
+      idleTimeoutMs: 40,
+      timeoutMs: 400,
+      noOutputTimedOut: true,
+      stderr: "Claude CLI produced no output before the idle timeout",
+    },
+    {
+      idleTimeoutMs: 400,
+      timeoutMs: 40,
+      noOutputTimedOut: false,
+      stderr: "Claude CLI exceeded the hard timeout",
+    },
+  ])("preserves the exact timeout result: $stderr", async (request) => {
+    const executable = await executableScript("setInterval(() => {}, 1000);");
+    await expect(runCommand(executable, { argv: ["-p"], ...request })).resolves.toMatchObject({
+      exitCode: 124,
+      timedOut: true,
+      noOutputTimedOut: request.noOutputTimedOut,
+      stderr: request.stderr,
+    });
+  });
+
+  it.each([
+    { name: "spawn", command: "/definitely/not/a/claude-command", error: "ENOENT" },
+    { name: "secret input", command: process.execPath, error: "secret delivery failed" },
+    { name: "progress", command: process.execPath, error: "progress delivery failed" },
+  ])("surfaces $name failures in the invocation result", async ({ name, command, error }) => {
+    const request = { argv: ["-p"], idleTimeoutMs: 1_000, timeoutMs: 5_000 };
+    await expect(
+      runCommand(command, request, {
+        argv: [command, "-e", 'process.stdout.write("progress"); setInterval(() => {}, 1000)'],
+        ...(name === "secret input"
+          ? {
+              secretInput: {
+                fd: 3,
+                createData: () => {
+                  throw new Error(error);
+                },
+              },
+            }
+          : {}),
+        ...(name === "progress"
+          ? {
+              client: {
+                async request<T>(): Promise<T> {
+                  throw new Error(error);
+                },
+              } satisfies NodeHostClient,
+            }
+          : {}),
+      }),
+    ).resolves.toMatchObject({
+      exitCode: 1,
+      success: false,
+      timedOut: false,
+      error: expect.stringContaining(error),
+      stderr: expect.stringContaining(error),
+    });
+  });
+
   it("terminates an active Claude command when its invoke is cancelled", async () => {
-    const executable = await executableScript(`setInterval(() => {}, 1000);`);
+    const executable = await executableScript(
+      `process.stdout.write("ready"); setInterval(() => {}, 1000);`,
+    );
     const controller = new AbortController();
     const request = { argv: ["-p"], idleTimeoutMs: 5_000, timeoutMs: 10_000 };
-    const run = runClaudeCliNodeCommand({
-      client: client([]),
-      frame: frame(request),
-      request,
-      argv: [executable, ...request.argv],
-      cwd: undefined,
-      env: process.env as Record<string, string>,
-      timeoutMs: request.timeoutMs,
+    const calls: Array<{ method: string; params: unknown }> = [];
+    const run = runCommand(executable, request, {
+      client: client(calls),
       signal: controller.signal,
     });
 
+    await vi.waitFor(() =>
+      expect(calls).toContainEqual(expect.objectContaining({ method: "node.invoke.progress" })),
+    );
     controller.abort();
 
     await expect(run).resolves.toMatchObject({
       exitCode: 130,
       success: false,
+      timedOut: false,
       stderr: expect.stringContaining("cancelled"),
     });
   });
@@ -527,16 +630,7 @@ writeChunk();`,
     const request = { argv: ["-p"], idleTimeoutMs: 5_000, timeoutMs: 10_000 };
 
     await expect(
-      runClaudeCliNodeCommand({
-        client: client([]),
-        frame: frame(request),
-        request,
-        argv: [executable, ...request.argv],
-        cwd: undefined,
-        env: process.env as Record<string, string>,
-        timeoutMs: request.timeoutMs,
-        signal: controller.signal,
-      }),
+      runCommand(executable, request, { signal: controller.signal }),
     ).resolves.toMatchObject({ exitCode: 130, success: false });
     await expect(fs.stat(marker)).rejects.toThrow();
   });
diff --git a/src/node-host/invoke-agent-cli-claude.ts b/src/node-host/invoke-agent-cli-claude.ts
index 337bdfbcb15c..1ef07d24ab7e 100644
--- a/src/node-host/invoke-agent-cli-claude.ts
+++ b/src/node-host/invoke-agent-cli-claude.ts
@@ -1,17 +1,12 @@
 /** Validates and streams one approval-gated Claude CLI turn on a headless node. */
-import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { StringDecoder } from "node:string_decoder";
-import { signalProcessTree } from "../process/kill-tree.js";
-import {
-  addSecretInputStdio,
-  type SpawnStdioEntry,
-  writeSecretInputToChild,
-} from "../process/spawn-secret-input.js";
-import type { SpawnSecretInput } from "../process/supervisor/types.js";
-import { resolveSafeChildProcessInvocation } from "../process/windows-command.js";
+import { logWarn } from "../logger.js";
+import { getProcessSupervisor } from "../process/supervisor/index.js";
+import type { RunExit, SpawnSecretInput } from "../process/supervisor/types.js";
 import { truncateUtf8Suffix } from "../utils/utf8-truncate.js";
 import type { NodeHostClient } from "./client.js";
 import type { ClaudeCliNodeRunParams } from "./invoke-agent-cli-claude-params.js";
@@ -67,207 +62,160 @@ export async function runClaudeCliNodeCommand(params: {
     if (params.signal?.aborted) {
       return cancelledResult();
     }
-    return await new Promise<RunResult>((resolve) => {
-      let settled = false;
-      let hardTimedOut = false;
-      let idleTimedOut = false;
-      let cancelled = false;
-      let truncated = false;
-      let outputBytes = 0;
-      let stderr = "";
-      const decoder = new StringDecoder("utf8");
-      const stderrDecoder = new StringDecoder("utf8");
-      const terminalDecoder = new StringDecoder("utf8");
-      let terminalLineBuffer = "";
-      let terminalLineTouchesTruncation = false;
-      let terminalResultLine: string | undefined;
-      const invocation = resolveSafeChildProcessInvocation({
+    const supervisor = getProcessSupervisor();
+    const runId = randomUUID();
+    let cancelled = false;
+    let truncated = false;
+    let outputBytes = 0;
+    let stderr = "";
+    let terminalLineBuffer = "";
+    let terminalLineTouchesTruncation = false;
+    let terminalResultLine: string | undefined;
+    const decoder = new StringDecoder("utf8");
+    const stderrDecoder = new StringDecoder("utf8");
+    const terminalDecoder = new StringDecoder("utf8");
+    const progress = createNodeInvokeProgressWriter({
+      client: params.client,
+      frame: params.frame,
+      idleTimeoutMs: params.request.idleTimeoutMs,
+      onError: () => supervisor.cancel(runId),
+    });
+    const abortRun = () => {
+      cancelled = true;
+      supervisor.cancel(runId);
+    };
+    const retain = (chunk: Buffer) => {
+      const remaining = Math.max(0, OUTPUT_CAP_BYTES - outputBytes);
+      const retained = chunk.subarray(0, remaining);
+      outputBytes += retained.length;
+      truncated ||= retained.length !== chunk.length;
+      return retained;
+    };
+    const captureTerminalLines = (raw: Buffer, touchesTruncation: boolean) => {
+      terminalLineBuffer += terminalDecoder.write(raw);
+      terminalLineTouchesTruncation ||= touchesTruncation;
+      for (let newline = terminalLineBuffer.indexOf("\n"); newline >= 0;) {
+        const line = terminalLineBuffer.slice(0, newline).replace(/\r$/u, "");
+        terminalLineBuffer = terminalLineBuffer.slice(newline + 1);
+        if (
+          terminalLineTouchesTruncation &&
+          Buffer.byteLength(line, "utf8") <= TERMINAL_EVENT_MAX_BYTES &&
+          isClaudeResultLine(line)
+        ) {
+          terminalResultLine = line;
+        }
+        terminalLineTouchesTruncation = touchesTruncation;
+        newline = terminalLineBuffer.indexOf("\n");
+      }
+      if (Buffer.byteLength(terminalLineBuffer, "utf8") > TERMINAL_EVENT_MAX_BYTES) {
+        terminalLineBuffer = "";
+        terminalLineTouchesTruncation = false;
+      }
+    };
+
+    let exit: RunExit | undefined;
+    let runError: Error | undefined;
+    params.signal?.addEventListener("abort", abortRun, { once: true });
+    try {
+      const runPromise = supervisor.spawn({
+        runId,
+        sessionId: params.request.sessionKey ?? params.frame.id,
+        backendId: "node-host-claude",
+        mode: "child",
         argv,
-        cwd: params.cwd,
-        env: params.env ?? process.env,
-      });
-      const stdio: SpawnStdioEntry[] = ["pipe", "pipe", "pipe"];
-      addSecretInputStdio(stdio, params.secretInput);
-      const child = spawn(invocation.command, invocation.args, {
         cwd: params.cwd,
         env: params.env,
-        stdio,
-        ...(process.platform !== "win32" ? { detached: true } : {}),
-        windowsHide: invocation.windowsHide,
-        windowsVerbatimArguments: invocation.windowsVerbatimArguments,
-      }) as ChildProcessWithoutNullStreams;
-
-      const kill = () => {
-        const pid = child.pid;
-        if (typeof pid === "number" && pid > 0) {
-          signalProcessTree(pid, "SIGKILL", { detached: process.platform !== "win32" });
-        }
-        try {
-          child.kill("SIGKILL");
-        } catch {
-          // Best effort; close/error settles the result.
-        }
-      };
-      const progress = createNodeInvokeProgressWriter({
-        client: params.client,
-        frame: params.frame,
-        idleTimeoutMs: params.request.idleTimeoutMs,
-        onError: kill,
+        exactEnv: true,
+        input: params.request.stdin ?? "",
+        secretInput: params.secretInput,
+        timeoutMs: params.timeoutMs ?? params.request.timeoutMs,
+        noOutputTimeoutMs: params.request.idleTimeoutMs,
+        captureOutput: false,
+        onStdoutRaw: (raw) => {
+          const retained = retain(raw);
+          captureTerminalLines(retained, false);
+          if (retained.length < raw.length) {
+            captureTerminalLines(raw.subarray(retained.length), true);
+          }
+          if (retained.length === 0) {
+            progress.queueHeartbeat();
+            return;
+          }
+          void progress.write(decoder.write(retained));
+        },
+        onStderrRaw: (raw) => {
+          retain(raw);
+          stderr = truncateUtf8Suffix(`${stderr}${stderrDecoder.write(raw)}`, STDERR_TAIL_BYTES);
+          progress.queueHeartbeat();
+        },
       });
-      const abortRun = () => {
-        cancelled = true;
-        kill();
-      };
-      params.signal?.addEventListener("abort", abortRun, { once: true });
       if (params.signal?.aborted) {
         abortRun();
       }
-      const hardTimer = setTimeout(() => {
-        hardTimedOut = true;
-        kill();
-      }, params.timeoutMs ?? params.request.timeoutMs);
-      let idleTimer: ReturnType<typeof setTimeout>;
-      const resetIdleTimer = () => {
-        clearTimeout(idleTimer);
-        idleTimer = setTimeout(() => {
-          idleTimedOut = true;
-          kill();
-        }, params.request.idleTimeoutMs);
-      };
-      resetIdleTimer();
+      const run = await runPromise;
+      if (promptDir && run.waitForExtinction) {
+        const ownedPromptDir = promptDir;
+        promptDir = undefined;
+        // Descendants may still own this file after their root result is already visible.
+        void run
+          .waitForExtinction()
+          .then(() => fs.rm(ownedPromptDir, { recursive: true, force: true }))
+          .catch((error: unknown) => {
+            logWarn(`Claude CLI system prompt cleanup failed: ${String(error)}`);
+          });
+      }
+      exit = await run.wait();
+    } catch (error) {
+      runError = error instanceof Error ? error : new Error(String(error));
+    } finally {
+      params.signal?.removeEventListener("abort", abortRun);
+      progress.stopHeartbeats();
+    }
 
-      const retain = (chunk: Buffer): Buffer => {
-        if (outputBytes >= OUTPUT_CAP_BYTES) {
-          truncated = true;
-          return Buffer.alloc(0);
-        }
-        const remaining = OUTPUT_CAP_BYTES - outputBytes;
-        const retained = chunk.length > remaining ? chunk.subarray(0, remaining) : chunk;
-        outputBytes += retained.length;
-        if (retained.length !== chunk.length) {
-          truncated = true;
-        }
-        return retained;
-      };
+    void progress.write(decoder.end());
+    terminalLineBuffer += terminalDecoder.end();
+    stderr = truncateUtf8Suffix(`${stderr}${stderrDecoder.end()}`, STDERR_TAIL_BYTES);
+    if (
+      terminalLineTouchesTruncation &&
+      Buffer.byteLength(terminalLineBuffer, "utf8") <= TERMINAL_EVENT_MAX_BYTES &&
+      isClaudeResultLine(terminalLineBuffer)
+    ) {
+      terminalResultLine = terminalLineBuffer;
+    }
+    if (truncated && terminalResultLine) {
+      void progress.write(`\n${terminalResultLine}\n`);
+    }
+    await progress.flush();
+    progress.stop();
 
-      const captureTerminalLines = (raw: Buffer, touchesTruncation: boolean) => {
-        terminalLineBuffer += terminalDecoder.write(raw);
-        terminalLineTouchesTruncation ||= touchesTruncation;
-        while (true) {
-          const newline = terminalLineBuffer.indexOf("\n");
-          if (newline < 0) {
-            break;
-          }
-          const line = terminalLineBuffer.slice(0, newline).replace(/\r$/u, "");
-          terminalLineBuffer = terminalLineBuffer.slice(newline + 1);
-          if (
-            terminalLineTouchesTruncation &&
-            Buffer.byteLength(line, "utf8") <= TERMINAL_EVENT_MAX_BYTES &&
-            isClaudeResultLine(line)
-          ) {
-            terminalResultLine = line;
-          }
-          terminalLineTouchesTruncation = touchesTruncation;
-        }
-        if (Buffer.byteLength(terminalLineBuffer, "utf8") > TERMINAL_EVENT_MAX_BYTES) {
-          terminalLineBuffer = "";
-          terminalLineTouchesTruncation = false;
-        }
-      };
-      // Output pipes can fail independently; child close/error remains authoritative.
-      const ignoreOutputStreamError = () => {};
-      child.stdout.on("error", ignoreOutputStreamError);
-      child.stderr.on("error", ignoreOutputStreamError);
-      child.stdout.on("data", (raw: Buffer) => {
-        const retained = retain(raw);
-        if (retained.length > 0) {
-          captureTerminalLines(retained, false);
-        }
-        if (retained.length < raw.length) {
-          captureTerminalLines(raw.subarray(retained.length), true);
-        }
-        // The Gateway's inactivity timer observes stdout progress events only;
-        // keep the node-local kill timer on the same signal to avoid orphan runs.
-        resetIdleTimer();
-        if (retained.length === 0) {
-          progress.queueHeartbeat();
-          return;
-        }
-        const text = decoder.write(retained);
-        void progress.write(text, child.stdout);
-      });
-      child.stderr.on("data", (raw: Buffer) => {
-        retain(raw);
-        stderr = truncateUtf8Suffix(`${stderr}${stderrDecoder.write(raw)}`, STDERR_TAIL_BYTES);
-        resetIdleTimer();
-        progress.queueHeartbeat();
-      });
-      child.stdin.on("error", () => {});
-      child.stdin.end(params.request.stdin ?? "");
-
-      const finish = async (exitCode: number | null, error?: Error) => {
-        if (settled) {
-          return;
-        }
-        settled = true;
-        clearTimeout(hardTimer);
-        clearTimeout(idleTimer);
-        progress.stopHeartbeats();
-        params.signal?.removeEventListener("abort", abortRun);
-        const finalText = decoder.end();
-        if (finalText) {
-          void progress.write(finalText);
-        }
-        const terminalText = terminalDecoder.end();
-        if (terminalText) {
-          terminalLineBuffer += terminalText;
-        }
-        const finalStderr = stderrDecoder.end();
-        if (finalStderr) {
-          stderr = truncateUtf8Suffix(`${stderr}${finalStderr}`, STDERR_TAIL_BYTES);
-        }
-        if (
-          terminalLineTouchesTruncation &&
-          Buffer.byteLength(terminalLineBuffer, "utf8") <= TERMINAL_EVENT_MAX_BYTES &&
-          isClaudeResultLine(terminalLineBuffer)
-        ) {
-          terminalResultLine = terminalLineBuffer;
-        }
-        if (truncated && terminalResultLine) {
-          void progress.write(`\n${terminalResultLine}\n`);
-        }
-        await progress.flush();
-        progress.stop();
-        const timeoutMessage = idleTimedOut
-          ? "Claude CLI produced no output before the idle timeout"
-          : hardTimedOut
-            ? "Claude CLI exceeded the hard timeout"
-            : "";
-        const finalError = progress.error ?? error;
-        const cancelledMessage = cancelled ? "Claude CLI invocation cancelled" : "";
-        resolve({
-          exitCode: exitCode ?? (idleTimedOut || hardTimedOut ? 124 : cancelled ? 130 : 1),
-          timedOut: idleTimedOut || hardTimedOut,
-          noOutputTimedOut: idleTimedOut,
-          success: exitCode === 0 && !idleTimedOut && !hardTimedOut && !cancelled && !finalError,
-          stdout: "",
-          stderr: truncateUtf8Suffix(
-            [stderr, timeoutMessage, cancelledMessage, finalError?.message]
-              .filter(Boolean)
-              .join("\n"),
-            STDERR_TAIL_BYTES,
-          ),
-          error: finalError?.message ?? null,
-          truncated,
-        });
-      };
-      void writeSecretInputToChild(child, params.secretInput).catch((error: unknown) => {
-        kill();
-        void finish(null, error instanceof Error ? error : new Error(String(error)));
-      });
-      child.once("error", (error) => void finish(null, error));
-      child.once("close", (code) => void finish(code));
-    });
+    const idleTimedOut = !cancelled && exit?.noOutputTimedOut === true;
+    const timedOut = !cancelled && exit?.timedOut === true;
+    const timeoutMessage = idleTimedOut
+      ? "Claude CLI produced no output before the idle timeout"
+      : timedOut
+        ? "Claude CLI exceeded the hard timeout"
+        : "";
+    const finalError = progress.error ?? runError;
+    return {
+      exitCode: cancelled ? 130 : (exit?.exitCode ?? (timedOut ? 124 : 1)),
+      timedOut,
+      noOutputTimedOut: idleTimedOut,
+      success: exit?.exitCode === 0 && !timedOut && !cancelled && !finalError,
+      stdout: "",
+      stderr: truncateUtf8Suffix(
+        [
+          stderr,
+          timeoutMessage,
+          cancelled ? "Claude CLI invocation cancelled" : "",
+          finalError?.message,
+        ]
+          .filter(Boolean)
+          .join("\n"),
+        STDERR_TAIL_BYTES,
+      ),
+      error: finalError?.message ?? null,
+      truncated,
+    };
   } finally {
     if (promptDir) {
       await fs.rm(promptDir, { recursive: true, force: true });
diff --git a/src/process/decoded-output.ts b/src/process/decoded-output.ts
index afea7338f988..aca06cfc4e99 100644
--- a/src/process/decoded-output.ts
+++ b/src/process/decoded-output.ts
@@ -1,7 +1,11 @@
 import type { Readable } from "node:stream";
 import { createWindowsOutputDecoder } from "../infra/windows-encoding.js";
 
-export function onDecodedOutput(stream: Readable, listener: (chunk: string) => void): void {
+export function onDecodedOutput(
+  stream: Readable,
+  listener: (chunk: string) => void,
+  onRaw?: (chunk: Buffer) => void,
+): void {
   const decoder = createWindowsOutputDecoder();
   const emit = (text: string) => {
     if (text) {
@@ -16,7 +20,10 @@ export function onDecodedOutput(stream: Readable, listener: (chunk: string) => v
     flushed = true;
     emit(decoder.flush());
   };
-  stream.on("data", (chunk: Buffer | string) => emit(decoder.decode(chunk)));
+  stream.on("data", (chunk: Buffer | string) => {
+    onRaw?.(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    emit(decoder.decode(chunk));
+  });
   stream.once("end", flush);
   stream.once("close", flush);
 }
diff --git a/src/process/supervisor/adapters/child-stdin.ts b/src/process/supervisor/adapters/child-stdin.ts
new file mode 100644
index 000000000000..c791d4120767
--- /dev/null
+++ b/src/process/supervisor/adapters/child-stdin.ts
@@ -0,0 +1,65 @@
+import type { Writable } from "node:stream";
+import type { ManagedRunStdin } from "../types.js";
+
+/** Keep direct children and service relays on the same observable stdin lifecycle. */
+export function createManagedChildStdin(
+  stream: Writable | null | undefined,
+): ManagedRunStdin | undefined {
+  if (!stream) {
+    return undefined;
+  }
+  let ended = stream.writableEnded || stream.writableFinished;
+  let destroyed = stream.destroyed;
+  stream.once("finish", () => {
+    ended = true;
+  });
+  stream.once("close", () => {
+    ended = true;
+    destroyed = true;
+  });
+  stream.once("error", () => {
+    destroyed = true;
+  });
+  return {
+    get destroyed() {
+      return destroyed || stream.destroyed;
+    },
+    get writable() {
+      return !destroyed && !ended && stream.writable;
+    },
+    get writableEnded() {
+      return ended || stream.writableEnded;
+    },
+    get writableFinished() {
+      return stream.writableFinished;
+    },
+    write(data, callback) {
+      if (destroyed || ended || !stream.writable) {
+        callback?.(new Error("stdin is not writable"));
+        return;
+      }
+      try {
+        stream.write(data, callback);
+      } catch (error) {
+        callback?.(error instanceof Error ? error : new Error(String(error)));
+      }
+    },
+    end() {
+      ended = true;
+      try {
+        stream.end();
+      } catch {
+        // Closing an already-failed child pipe is best effort.
+      }
+    },
+    destroy() {
+      ended = true;
+      destroyed = true;
+      try {
+        stream.destroy();
+      } catch {
+        // Destroying an already-failed child pipe is best effort.
+      }
+    },
+  };
+}
diff --git a/src/process/supervisor/adapters/child.service-lifecycle.test.ts b/src/process/supervisor/adapters/child.service-lifecycle.test.ts
index 5c771865900e..4bbf5c04e23a 100644
--- a/src/process/supervisor/adapters/child.service-lifecycle.test.ts
+++ b/src/process/supervisor/adapters/child.service-lifecycle.test.ts
@@ -135,6 +135,7 @@ describe.skipIf(process.platform === "win32")("service-managed child lifecycle",
 
     expect(elapsed).toBeLessThan(300);
     expect(isAlive(descendantPid)).toBe(true);
+    await adapter.waitForExtinction?.();
     await waitFor(() => !isAlive(descendantPid));
   });
 
diff --git a/src/process/supervisor/adapters/child.test.ts b/src/process/supervisor/adapters/child.test.ts
index 22c215d4b8cd..9e4ed0f3569b 100644
--- a/src/process/supervisor/adapters/child.test.ts
+++ b/src/process/supervisor/adapters/child.test.ts
@@ -958,14 +958,16 @@ describe("createChildAdapter", () => {
     });
     const first = vi.fn();
     const second = vi.fn();
+    const raw = vi.fn();
 
-    adapter.onStdout(first);
+    adapter.onStdout(first, raw);
     adapter.onStdout(second);
     child.stdout?.emit("data", Buffer.from([0xb2]));
 
     expect(createWindowsOutputDecoderMock).toHaveBeenCalledTimes(2);
     expect(first).toHaveBeenCalledWith("first");
     expect(second).toHaveBeenCalledWith("second");
+    expect(raw).toHaveBeenCalledWith(Buffer.from([0xb2]));
   });
 
   it("guards stream errors before output listeners are registered", async () => {
diff --git a/src/process/supervisor/adapters/child.ts b/src/process/supervisor/adapters/child.ts
index e9bfe4b1bb3e..9b493cfed66e 100644
--- a/src/process/supervisor/adapters/child.ts
+++ b/src/process/supervisor/adapters/child.ts
@@ -21,7 +21,8 @@ import {
   resolveWindowsCommandShim,
 } from "../../windows-command.js";
 import { createServiceChildRelayAdapter } from "../service-child-relay-host.js";
-import type { ManagedRunStdin, SpawnProcessAdapter, SpawnSecretInput } from "../types.js";
+import type { SpawnProcessAdapter, SpawnSecretInput } from "../types.js";
+import { createManagedChildStdin } from "./child-stdin.js";
 import { toStringEnv } from "./env.js";
 
 const FORCE_KILL_WAIT_FALLBACK_MS = 4000;
@@ -193,77 +194,19 @@ export async function createChildAdapter(params: {
   child.stdout.on("error", ignoreOutputStreamError);
   child.stderr.on("error", ignoreOutputStreamError);
   const childStdin = spawned.child.stdin;
-  let stdinDestroyed = childStdin?.destroyed ?? false;
-  let stdinEnded = childStdin?.writableEnded === true || childStdin?.writableFinished === true;
-  if (childStdin) {
-    childStdin.once("finish", () => {
-      stdinEnded = true;
-    });
-    childStdin.once("close", () => {
-      stdinEnded = true;
-      stdinDestroyed = true;
-    });
-    childStdin.once("error", () => {
-      stdinDestroyed = true;
-    });
-    if (params.input !== undefined) {
-      childStdin.write(params.input);
-      stdinEnded = true;
-      childStdin.end();
-    } else if (stdinMode === "pipe-closed") {
-      stdinEnded = true;
-      childStdin.end();
-    }
+  const stdin = createManagedChildStdin(childStdin);
+  if (params.input !== undefined) {
+    childStdin?.write(params.input);
+    stdin?.end();
+  } else if (stdinMode === "pipe-closed") {
+    stdin?.end();
   }
 
-  const stdin: ManagedRunStdin | undefined = childStdin
-    ? {
-        get destroyed() {
-          return stdinDestroyed || childStdin.destroyed;
-        },
-        get writable() {
-          return !stdinDestroyed && !stdinEnded && childStdin.writable;
-        },
-        get writableEnded() {
-          return stdinEnded || childStdin.writableEnded;
-        },
-        get writableFinished() {
-          return childStdin.writableFinished;
-        },
-        write: (data: string, cb?: (err?: Error | null) => void) => {
-          if (stdinDestroyed || stdinEnded || !childStdin.writable) {
-            cb?.(new Error("stdin is not writable"));
-            return;
-          }
-          try {
-            childStdin.write(data, cb);
-          } catch (err) {
-            cb?.(err as Error);
-          }
-        },
-        end: () => {
-          try {
-            stdinEnded = true;
-            childStdin.end();
-          } catch {
-            // ignore close errors
-          }
-        },
-        destroy: () => {
-          try {
-            stdinDestroyed = true;
-            stdinEnded = true;
-            childStdin.destroy();
-          } catch {
-            // ignore destroy errors
-          }
-        },
-      }
-    : undefined;
+  const onStdout: ChildAdapter["onStdout"] = (listener, onRaw) =>
+    onDecodedOutput(child.stdout, listener, onRaw);
 
-  const onStdout = (listener: (chunk: string) => void) => onDecodedOutput(child.stdout, listener);
-
-  const onStderr = (listener: (chunk: string) => void) => onDecodedOutput(child.stderr, listener);
+  const onStderr: ChildAdapter["onStderr"] = (listener, onRaw) =>
+    onDecodedOutput(child.stderr, listener, onRaw);
 
   let waitResult: { code: number | null; signal: NodeJS.Signals | null } | null = null;
   let waitError: unknown;
diff --git a/src/process/supervisor/service-child-relay-host.ts b/src/process/supervisor/service-child-relay-host.ts
index 47ffb63d30b2..21028f2c0f60 100644
--- a/src/process/supervisor/service-child-relay-host.ts
+++ b/src/process/supervisor/service-child-relay-host.ts
@@ -1,11 +1,12 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import type { Duplex, Readable, Writable } from "node:stream";
+import type { Duplex, Readable } from "node:stream";
 import { fileURLToPath } from "node:url";
-import { toErrorObject } from "../../infra/errors.js";
 import { resolveRuntimeWorkerUrl } from "../../infra/runtime-worker-url.js";
+import { createDeferredCore } from "../../shared/deferred.js";
 import { onDecodedOutput } from "../decoded-output.js";
 import { addSecretInputStdio, writeSecretInputToChild } from "../spawn-secret-input.js";
+import { createManagedChildStdin } from "./adapters/child-stdin.js";
 import { toStringEnv } from "./adapters/env.js";
 import {
   encodeServiceChildMessage,
@@ -13,7 +14,7 @@ import {
   type ServiceChildRelayMessage,
   type ServiceChildStart,
 } from "./service-child-protocol.js";
-import type { ManagedRunStdin, SpawnProcessAdapter, SpawnSecretInput } from "./types.js";
+import type { SpawnProcessAdapter, SpawnSecretInput } from "./types.js";
 
 type ServiceAdapter = SpawnProcessAdapter<NodeJS.Signals | null>;
 type AuthorityState = "starting" | "active" | "closing" | "closed" | "identity-lost";
@@ -49,101 +50,57 @@ function reserveStdioEntry(stdio: StdioEntry[], value: StdioEntry): number {
   return fd;
 }
 
-function createManagedStdin(stream: Writable | null): ManagedRunStdin | undefined {
-  if (!stream) {
-    return undefined;
-  }
-  let ended = stream.writableEnded || stream.writableFinished;
-  let destroyed = stream.destroyed;
-  stream.once("finish", () => {
-    ended = true;
-  });
-  stream.once("close", () => {
-    ended = true;
-    destroyed = true;
-  });
-  stream.once("error", () => {
-    destroyed = true;
-  });
-  return {
-    get destroyed() {
-      return destroyed || stream.destroyed;
-    },
-    get writable() {
-      return !destroyed && !ended && stream.writable;
-    },
-    get writableEnded() {
-      return ended || stream.writableEnded;
-    },
-    get writableFinished() {
-      return stream.writableFinished;
-    },
-    write(data, callback) {
-      if (destroyed || ended || !stream.writable) {
-        callback?.(new Error("stdin is not writable"));
-        return;
-      }
-      try {
-        stream.write(data, callback);
-      } catch (error) {
-        callback?.(toErrorObject(error, "stdin write failed"));
-      }
-    },
-    end() {
-      ended = true;
-      stream.end();
-    },
-    destroy() {
-      ended = true;
-      destroyed = true;
-      stream.destroy();
-    },
-  };
-}
-
 function createOutputRelay(stream: Readable) {
   const listeners = new Set<(chunk: string) => void>();
-  const pending: string[] = [];
+  const rawListeners = new Set<(chunk: Buffer) => void>();
+  const pending: Array<string | Buffer> = [];
   let pendingBytes = 0;
   let active = false;
-  const activate = (deliver: boolean) => {
+  const deliver = (chunk: string | Buffer) => {
+    if (typeof chunk === "string") {
+      listeners.forEach((listener) => listener(chunk));
+    } else {
+      rawListeners.forEach((listener) => listener(chunk));
+    }
+  };
+  const activate = (keepOutput: boolean) => {
     if (active) {
       return;
     }
     active = true;
-    if (deliver) {
-      for (const text of pending) {
-        for (const listener of listeners) {
-          listener(text);
-        }
-      }
+    if (keepOutput) {
+      pending.forEach(deliver);
     }
     pending.length = 0;
     pendingBytes = 0;
     stream.resume();
   };
-  onDecodedOutput(stream, (text) => {
+  const enqueue = (chunk: string | Buffer) => {
     if (active) {
-      for (const listener of listeners) {
-        listener(text);
-      }
+      deliver(chunk);
       return;
     }
-    pending.push(text);
-    pendingBytes += Buffer.byteLength(text);
-    // Bound host memory while retaining the rest in the native pipe until subscription.
-    if (pendingBytes >= stream.readableHighWaterMark) {
-      stream.pause();
+    pending.push(chunk);
+    if (Buffer.isBuffer(chunk)) {
+      pendingBytes += chunk.length;
+      if (pendingBytes >= stream.readableHighWaterMark) {
+        stream.pause();
+      }
     }
-  });
+  };
+  onDecodedOutput(stream, enqueue, enqueue);
   return {
-    subscribe: (listener: (chunk: string) => void) => {
+    subscribe: (listener: (chunk: string) => void, onRaw?: (chunk: Buffer) => void) => {
       listeners.add(listener);
+      if (onRaw) {
+        rawListeners.add(onRaw);
+      }
       activate(true);
     },
     drain: () => activate(false),
     clear: () => {
       listeners.clear();
+      rawListeners.clear();
       pending.length = 0;
       pendingBytes = 0;
     },
@@ -215,6 +172,8 @@ export async function createServiceChildRelayAdapter(params: {
   let rejectWait: ((error: Error) => void) | undefined;
   let waitPromise: Promise<{ code: number | null; signal: NodeJS.Signals | null }> | undefined;
   let waitSettled = false;
+  const extinction = createDeferredCore();
+  void extinction.promise.catch(() => undefined);
 
   const settleWait = () => {
     if (waitSettled) {
@@ -256,6 +215,7 @@ export async function createServiceChildRelayAdapter(params: {
       rejectStartup(waitError);
     }
     settleWait();
+    extinction.reject(waitError);
   };
 
   let pending = "";
@@ -314,6 +274,7 @@ export async function createServiceChildRelayAdapter(params: {
     state = "closed";
     rootResult ??= { code: null, signal: requestedSignal ?? null };
     settleWait();
+    extinction.resolve();
   });
   control.on("error", (error) => {
     loseIdentity(error.message);
@@ -368,7 +329,7 @@ export async function createServiceChildRelayAdapter(params: {
     throw startupError ?? secretDeliveryError;
   }
 
-  const stdin = createManagedStdin(relay.stdin);
+  const stdin = createManagedChildStdin(relay.stdin);
   if (params.input !== undefined) {
     stdin?.write(params.input);
     stdin?.end();
@@ -417,6 +378,7 @@ export async function createServiceChildRelayAdapter(params: {
       });
       return await waitPromise;
     },
+    waitForExtinction: () => extinction.promise,
     kill,
     dispose: () => {
       stdoutRelay.clear();
diff --git a/src/process/supervisor/supervisor.test.ts b/src/process/supervisor/supervisor.test.ts
index b790f5511d72..3b3f3be3bc75 100644
--- a/src/process/supervisor/supervisor.test.ts
+++ b/src/process/supervisor/supervisor.test.ts
@@ -143,24 +143,66 @@ describe("process supervisor", () => {
     expect(adapter.disposeMock).toHaveBeenCalledTimes(1);
   });
 
-  it("passes private secret input to the child adapter", async () => {
+  it.each([
+    { outcome: "process-tree extinction", failure: false },
+    { outcome: "cleanup identity loss", failure: true },
+  ])("retains root-result cancellation ownership until $outcome", async ({ failure }) => {
+    const extinction = createDeferred();
+    const adapter = Object.assign(createStubChildAdapter(), {
+      waitForExtinction: () => extinction.promise,
+    });
+    createChildAdapterMock.mockResolvedValue(adapter);
+    const supervisor = createProcessSupervisor();
+    const run = await spawnChild(supervisor, {
+      sessionId: "root-result-before-extinction",
+      scopeKey: "scope:root-result-before-extinction",
+      argv: createSilentIdleArgv(),
+    });
+    adapter.emitStdout("authentic root output");
+    adapter.settle(23);
+    const root = await run.wait();
+
+    expect(root).toMatchObject({ reason: "exit", exitCode: 23, stdout: "authentic root output" });
+    expect(adapter.disposeMock).not.toHaveBeenCalled();
+    supervisor.cancelScope("scope:root-result-before-extinction");
+    expect(adapter.killMock).toHaveBeenCalledWith("SIGTERM");
+    expect(supervisor.getRecord(run.runId)).toMatchObject({
+      state: "exited",
+      terminationReason: "exit",
+      exitCode: 23,
+    });
+
+    if (failure) {
+      extinction.reject(new Error("cleanup identity lost"));
+      await expect(run.waitForExtinction?.()).rejects.toThrow("cleanup identity lost");
+    } else {
+      extinction.resolve();
+      await expect(run.waitForExtinction?.()).resolves.toBeUndefined();
+    }
+    expect(adapter.disposeMock).toHaveBeenCalledOnce();
+    await expect(run.wait()).resolves.toBe(root);
+    supervisor.cancel(run.runId);
+    expect(adapter.killMock).toHaveBeenCalledOnce();
+  });
+
+  it("passes private secret input and exact environment to the child adapter", async () => {
     const adapter = createStubChildAdapter();
     createChildAdapterMock.mockResolvedValue(adapter);
-    const secretInput = {
-      fd: 3,
-      createData: () => Buffer.from("secret"),
-    };
+    const secretInput = { fd: 3, createData: () => Buffer.from("secret") };
 
     const supervisor = createProcessSupervisor();
     const run = await spawnChild(supervisor, {
       sessionId: "s1",
       argv: createWriteStdoutArgv("ok"),
+      exactEnv: true,
       secretInput,
     });
     adapter.settle(0);
     await run.wait();
 
-    expect(createChildAdapterMock).toHaveBeenCalledWith(expect.objectContaining({ secretInput }));
+    expect(createChildAdapterMock).toHaveBeenCalledWith(
+      expect.objectContaining({ exactEnv: true, secretInput }),
+    );
   });
 
   it("enforces no-output timeout for silent processes", async () => {
diff --git a/src/process/supervisor/supervisor.ts b/src/process/supervisor/supervisor.ts
index 1d92f5468503..9084a72b4d05 100644
--- a/src/process/supervisor/supervisor.ts
+++ b/src/process/supervisor/supervisor.ts
@@ -195,6 +195,7 @@ export function createProcessSupervisor(): ProcessSupervisor {
 
     let forcedReason: TerminationReason | null = startingRun.terminationReason ?? null;
     let settled = false;
+    let extinguished = false;
     let stdout = "";
     let stderr = "";
     let stdoutListener = input.onStdout;
@@ -222,7 +223,9 @@ export function createProcessSupervisor(): ProcessSupervisor {
     let cancelAdapter: ((reason: TerminationReason) => void) | null = null;
 
     const requestCancel = (reason: TerminationReason) => {
-      setForcedReason(reason);
+      if (!settled) {
+        setForcedReason(reason);
+      }
       cancelAdapter?.(reason);
     };
     startingRun.cancel = requestCancel;
@@ -292,6 +295,7 @@ export function createProcessSupervisor(): ProcessSupervisor {
               argv: input.argv,
               cwd: input.cwd,
               env: input.env,
+              exactEnv: input.exactEnv,
               windowsVerbatimArguments: input.windowsVerbatimArguments,
               input: input.input,
               stdinMode: input.stdinMode,
@@ -303,7 +307,7 @@ export function createProcessSupervisor(): ProcessSupervisor {
         ...(forcedReason ? { terminationReason: forcedReason } : {}),
       });
 
-      const clearTimers = () => {
+      const clearTimers = (includeForceKill = true) => {
         if (timeoutTimer) {
           clearTimeout(timeoutTimer);
           timeoutTimer = null;
@@ -312,14 +316,24 @@ export function createProcessSupervisor(): ProcessSupervisor {
           clearTimeout(noOutputTimer);
           noOutputTimer = null;
         }
-        if (forceKillTimer) {
+        if (includeForceKill && forceKillTimer) {
           clearTimeout(forceKillTimer);
           forceKillTimer = null;
         }
       };
 
+      const releaseAuthority = () => {
+        if (extinguished) {
+          return;
+        }
+        extinguished = true;
+        clearTimers();
+        adapter.dispose();
+        active.delete(runId);
+      };
+
       cancelAdapter = (reason: TerminationReason) => {
-        if (settled || cancelRequested) {
+        if (extinguished || cancelRequested) {
           return;
         }
         cancelRequested = true;
@@ -335,7 +349,7 @@ export function createProcessSupervisor(): ProcessSupervisor {
         }
         adapter.kill("SIGTERM");
         forceKillTimer = setTimeout(() => {
-          if (!settled) {
+          if (!extinguished) {
             adapter.kill("SIGKILL");
           }
         }, GRACEFUL_CANCEL_TIMEOUT_MS);
@@ -359,20 +373,29 @@ export function createProcessSupervisor(): ProcessSupervisor {
         );
       }
 
+      const onRawOutput = (listener?: (chunk: Buffer) => void) =>
+        listener &&
+        ((chunk: Buffer) => {
+          listener(chunk);
+          touchOutput();
+        });
+      const rawInput = input.mode === "child" ? input : undefined;
       adapter.onStdout((chunk) => {
         if (captureOutput) {
           stdout = appendCapturedOutput(stdout, chunk, "stdout", maxCapturedOutputChars);
         }
         stdoutListener?.(chunk);
         touchOutput();
-      });
+      }, onRawOutput(rawInput?.onStdoutRaw));
       adapter.onStderr((chunk) => {
         if (captureOutput) {
           stderr = appendCapturedOutput(stderr, chunk, "stderr", maxCapturedOutputChars);
         }
         stderrListener?.(chunk);
         touchOutput();
-      });
+      }, onRawOutput(rawInput?.onStderrRaw));
+
+      const adapterExtinction = adapter.waitForExtinction?.();
 
       const waitPromise = (async (): Promise<RunExit> => {
         const result = await adapter.wait();
@@ -383,9 +406,7 @@ export function createProcessSupervisor(): ProcessSupervisor {
         });
         const terminalReason = forcedReason ?? deadlineReason;
         settled = true;
-        clearTimers();
-        adapter.dispose();
-        active.delete(runId);
+        clearTimers(false);
 
         const reason: TerminationReason =
           terminalReason ?? (result.signal != null ? ("signal" as const) : ("exit" as const));
@@ -405,13 +426,19 @@ export function createProcessSupervisor(): ProcessSupervisor {
           exitCode: exit.exitCode,
           exitSignal: exit.exitSignal,
         });
+        if (!adapterExtinction) {
+          releaseAuthority();
+        }
         return exit;
       })().catch((err: unknown) => {
         if (!settled) {
           settled = true;
-          clearTimers();
-          active.delete(runId);
-          adapter.dispose();
+          clearTimers(false);
+          if (adapterExtinction) {
+            adapter.kill("SIGKILL");
+          } else {
+            releaseAuthority();
+          }
           registry.finalize(runId, {
             reason: "spawn-error",
             exitCode: null,
@@ -421,12 +448,23 @@ export function createProcessSupervisor(): ProcessSupervisor {
         throw err;
       });
 
+      const extinctionPromise = adapterExtinction
+        ? Promise.allSettled([waitPromise, adapterExtinction]).then(([, extinction]) => {
+            releaseAuthority();
+            if (extinction.status === "rejected") {
+              throw extinction.reason;
+            }
+          })
+        : undefined;
+      void extinctionPromise?.catch(() => undefined);
+
       const managedRun: ManagedRun = {
         runId,
         pid: adapter.pid,
         startedAtMs,
         stdin: adapter.stdin,
         wait: async () => await waitPromise,
+        ...(extinctionPromise ? { waitForExtinction: async () => await extinctionPromise } : {}),
         cancel: (reason = "manual-cancel") => {
           requestCancel(reason);
         },
diff --git a/src/process/supervisor/types.ts b/src/process/supervisor/types.ts
index d1459c8f11da..0a7c44a6c740 100644
--- a/src/process/supervisor/types.ts
+++ b/src/process/supervisor/types.ts
@@ -44,6 +44,8 @@ export type ManagedRun = {
   startedAtMs: number;
   stdin?: ManagedRunStdin;
   wait: () => Promise<RunExit>;
+  /** Present only when tree cleanup can outlive the root process result. */
+  waitForExtinction?: () => Promise<void>;
   cancel: (reason?: TerminationReason) => void;
   /** Stop delivering output callbacks before owner teardown kills the child. */
   detachOutput?: () => void;
@@ -68,9 +70,10 @@ export type SpawnProcessAdapter<WaitSignal = NodeJS.Signals | number | null> = {
   pid?: number;
   stdin?: ManagedRunStdin;
   oomScoreWrapperSelected?: boolean;
-  onStdout: (listener: (chunk: string) => void) => void;
-  onStderr: (listener: (chunk: string) => void) => void;
+  onStdout: (listener: (chunk: string) => void, onRaw?: (chunk: Buffer) => void) => void;
+  onStderr: (listener: (chunk: string) => void, onRaw?: (chunk: Buffer) => void) => void;
   wait: () => Promise<{ code: number | null; signal: WaitSignal }>;
+  waitForExtinction?: () => Promise<void>;
   kill: (signal?: NodeJS.Signals) => void;
   dispose: () => void;
 };
@@ -101,10 +104,14 @@ type SpawnBaseInput = {
 type SpawnChildInput = SpawnBaseInput & {
   mode: "child";
   argv: string[];
+  /** Preserve a caller-prepared environment without environment-mutating spawn wrappers. */
+  exactEnv?: true;
   windowsVerbatimArguments?: boolean;
   input?: string;
   stdinMode?: "inherit" | "pipe-open" | "pipe-closed";
   secretInput?: SpawnSecretInput;
+  onStdoutRaw?: (chunk: Buffer) => void;
+  onStderrRaw?: (chunk: Buffer) => void;
 };
 
 type SpawnPtyInput = SpawnBaseInput & {

From 1c5c878a96e3781ce029599c2a966158581383ce Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 15:40:07 -0700
Subject: [PATCH 116/124] fix(ui): show filtered agent skills (#127663)

Amp-Thread-ID: https://ampcode.com/threads/T-01a021f4-b547-7788-a916-d4a94cbd3e3b

Co-authored-by: Amp <amp@ampcode.com>
---
 .../panels-tools-skills.browser.test.ts       | 94 +++++++++++++++----
 ui/src/pages/agents/panels-tools-skills.ts    |  5 +-
 2 files changed, 79 insertions(+), 20 deletions(-)

diff --git a/ui/src/pages/agents/panels-tools-skills.browser.test.ts b/ui/src/pages/agents/panels-tools-skills.browser.test.ts
index c46df5ce5ebc..e62f19dcfbcc 100644
--- a/ui/src/pages/agents/panels-tools-skills.browser.test.ts
+++ b/ui/src/pages/agents/panels-tools-skills.browser.test.ts
@@ -55,6 +55,30 @@ function createBaseParams(overrides: Partial<Parameters<typeof renderAgentTools>
   };
 }
 
+function createSkill(
+  name: string,
+  options: { source?: string; bundled?: boolean; blockedByAgentFilter?: boolean } = {},
+): SkillStatusEntry {
+  return {
+    name,
+    description: `${name} skill`,
+    source: options.source ?? "openclaw-managed",
+    bundled: options.bundled ?? false,
+    filePath: `/tmp/skills/${name}/SKILL.md`,
+    baseDir: `/tmp/skills/${name}`,
+    skillKey: name,
+    always: false,
+    disabled: false,
+    blockedByAllowlist: false,
+    blockedByAgentFilter: options.blockedByAgentFilter ?? false,
+    eligible: true,
+    requirements: { bins: [], anyBins: [], env: [], config: [], os: [] },
+    missing: { bins: [], anyBins: [], env: [], config: [], os: [] },
+    configChecks: [],
+    install: [],
+  };
+}
+
 describe("agents tools panel (browser)", () => {
   it("renders catalog provenance and effective runtime tools", async () => {
     const container = document.createElement("div");
@@ -637,26 +661,58 @@ describe("agents tools panel (browser)", () => {
 });
 
 describe("agents skills panel (browser)", () => {
+  it("shows matches from default-collapsed groups while filtering", async () => {
+    const container = document.createElement("div");
+    const params: Parameters<typeof renderAgentSkills>[0] = {
+      agentId: "main",
+      canPatchConfig: true,
+      canUpdateConfig: true,
+      report: {
+        workspaceDir: "/tmp/workspace",
+        managedSkillsDir: "/tmp/skills",
+        agentId: "main",
+        skills: [
+          createSkill("Unique Built In Match", {
+            source: "openclaw-bundled",
+            bundled: true,
+          }),
+          createSkill("Installed Distractor"),
+        ],
+      },
+      loading: false,
+      error: null,
+      activeAgentId: "main",
+      configForm: { agents: { entries: { main: { default: true } } } },
+      configLoading: false,
+      configSaving: false,
+      configDirty: false,
+      filter: "",
+      onFilterChange: () => undefined,
+      onRefresh: () => undefined,
+      onToggle: () => undefined,
+      onClear: () => undefined,
+      onDisableAll: () => undefined,
+      onConfigReload: () => undefined,
+      onConfigSave: () => undefined,
+    };
+
+    render(renderAgentSkills(params), container);
+    await Promise.resolve();
+    const builtInGroup = container.querySelector<HTMLDetailsElement>(".agent-skills-group");
+    expect(builtInGroup?.open).toBe(false);
+
+    render(renderAgentSkills({ ...params, filter: "Unique Built In Match" }), container);
+    await Promise.resolve();
+    const filteredGroup = container.querySelector<HTMLDetailsElement>(".agent-skills-group");
+    expect(container.textContent).toContain("1 shown");
+    expect(filteredGroup?.open).toBe(true);
+    expect(filteredGroup?.querySelector(".agent-skill-row")?.textContent).toContain(
+      "Unique Built In Match",
+    );
+  });
+
   it("reflects an inherited default skill allowlist", async () => {
     const container = document.createElement("div");
-    const skill = (name: string, blockedByAgentFilter: boolean): SkillStatusEntry => ({
-      name,
-      description: `${name} skill`,
-      source: "openclaw-managed",
-      bundled: false,
-      filePath: `/tmp/skills/${name}/SKILL.md`,
-      baseDir: `/tmp/skills/${name}`,
-      skillKey: name,
-      always: false,
-      disabled: false,
-      blockedByAllowlist: false,
-      blockedByAgentFilter,
-      eligible: true,
-      requirements: { bins: [], anyBins: [], env: [], config: [], os: [] },
-      missing: { bins: [], anyBins: [], env: [], config: [], os: [] },
-      configChecks: [],
-      install: [],
-    });
 
     render(
       renderAgentSkills({
@@ -668,7 +724,7 @@ describe("agents skills panel (browser)", () => {
           managedSkillsDir: "/tmp/skills",
           agentId: "main",
           agentSkillFilter: ["github"],
-          skills: [skill("github", false), skill("weather", true)],
+          skills: [createSkill("github"), createSkill("weather", { blockedByAgentFilter: true })],
         },
         loading: false,
         error: null,
diff --git a/ui/src/pages/agents/panels-tools-skills.ts b/ui/src/pages/agents/panels-tools-skills.ts
index d0ebfbc501c7..c1c40d0c830a 100644
--- a/ui/src/pages/agents/panels-tools-skills.ts
+++ b/ui/src/pages/agents/panels-tools-skills.ts
@@ -841,6 +841,7 @@ export function renderAgentSkills(params: {
                     allowSet,
                     usingAllowlist,
                     editable,
+                    filterActive: Boolean(filter),
                     onToggle: params.onToggle,
                   }),
                 )}
@@ -858,10 +859,12 @@ function renderAgentSkillGroup(
     allowSet: Set<string>;
     usingAllowlist: boolean;
     editable: boolean;
+    filterActive: boolean;
     onToggle: (agentId: string, skillName: string, enabled: boolean) => void;
   },
 ) {
-  const collapsedByDefault = group.id === "workspace" || group.id === "built-in";
+  const collapsedByDefault =
+    !params.filterActive && (group.id === "workspace" || group.id === "built-in");
   return html`
     <details class="agent-skills-group" ?open=${!collapsedByDefault}>
       <summary class="agent-skills-header">

From c7c3a20a5842e28581d0a47bf2607e7d2b065d8c Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 15:40:47 -0700
Subject: [PATCH 117/124] fix(gateway): recover failed cloud worker reclaim
 (#127660)

Accepted reclaim results hand off to same-Gateway recovery so provider cleanup can retry without direct Crabbox intervention.

Related: #112106
---
 .../placement-dispatch-failure.ts             |  1 +
 .../placement-dispatch-test-harness.ts        |  8 ++++-
 .../placement-dispatch.test.ts                | 25 +++++++-------
 .../worker-environments/placement-dispatch.ts | 12 +++++++
 .../placement-force-abandon.test.ts           | 29 ++++++++--------
 .../placement-force-abandon.ts                | 11 ++-----
 .../placement-pending-failure.ts              | 33 +++++--------------
 .../placement-workspace-result.ts             | 29 ++++++++++++++++
 8 files changed, 87 insertions(+), 61 deletions(-)

diff --git a/src/gateway/worker-environments/placement-dispatch-failure.ts b/src/gateway/worker-environments/placement-dispatch-failure.ts
index d785cb5a6a20..d563137aa23e 100644
--- a/src/gateway/worker-environments/placement-dispatch-failure.ts
+++ b/src/gateway/worker-environments/placement-dispatch-failure.ts
@@ -50,6 +50,7 @@ export type WorkerDispatchPlacementStore = Pick<
   | "list"
   | "listPendingWorkspaceResults"
   | "markWorkspaceResultPending"
+  | "handoffWorkspaceResultRecovery"
   | "workspaceResultInstanceId"
   | "validateWorkspaceResultClaim"
   | "recordStagedWorkspaceResult"
diff --git a/src/gateway/worker-environments/placement-dispatch-test-harness.ts b/src/gateway/worker-environments/placement-dispatch-test-harness.ts
index f9a7cbb4a354..03e795e1b7d2 100644
--- a/src/gateway/worker-environments/placement-dispatch-test-harness.ts
+++ b/src/gateway/worker-environments/placement-dispatch-test-harness.ts
@@ -30,6 +30,7 @@ export function createHarness(
   options: {
     failAt?: DispatchStage;
     destroyFails?: boolean;
+    destroyFailureCount?: number;
     claimOnDrain?: boolean;
     reconcileFails?: boolean;
     reconcileFailureCount?: number;
@@ -64,6 +65,7 @@ export function createHarness(
   } = {},
 ) {
   const reconciledManifestRef = MANIFEST_REF.replaceAll("b", "c");
+  let remainingDestroyFailures = options.destroyFailureCount ?? 0;
   let remainingReconcileFailures = options.reconcileFailureCount ?? 0;
   let remainingLeaseFailures = options.leaseFailureCount ?? 0;
   let verifyCalls = 0;
@@ -127,6 +129,7 @@ export function createHarness(
     recordPlacementMoveError: (params) => placementStore.recordPlacementMoveError(params),
     markWorkspaceResultPending: (claim) => placementStore.markWorkspaceResultPending(claim),
     acceptWorkspaceResult: (claim) => placementStore.acceptWorkspaceResult(claim),
+    handoffWorkspaceResultRecovery: (claim) => placementStore.handoffWorkspaceResultRecovery(claim),
     cancelWorkspaceResultAndReleaseTurn: (claim) =>
       placementStore.cancelWorkspaceResultAndReleaseTurn(claim),
     completeWorkspaceResultAndReleaseTurn: (claim) =>
@@ -344,7 +347,10 @@ export function createHarness(
     }),
     destroy: vi.fn(async () => {
       log.push("teardown:destroy");
-      if (options.destroyFails) {
+      if (options.destroyFails || remainingDestroyFailures > 0) {
+        if (remainingDestroyFailures > 0) {
+          remainingDestroyFailures -= 1;
+        }
         if (options.destroyFailureState) {
           currentEnvironment = {
             ...attached,
diff --git a/src/gateway/worker-environments/placement-dispatch.test.ts b/src/gateway/worker-environments/placement-dispatch.test.ts
index 3bcc2fe17fe2..7bc84bd4576a 100644
--- a/src/gateway/worker-environments/placement-dispatch.test.ts
+++ b/src/gateway/worker-environments/placement-dispatch.test.ts
@@ -500,18 +500,16 @@ describe("worker placement dispatch", () => {
     expect(harness.placements.current()).toMatchObject({
       state: "draining",
       workspaceBaseManifestRef: harness.reconciledManifestRef,
-      turnClaim: { owner: "worker" },
+      turnClaim: null,
     });
-    expect(placementStore.listPendingWorkspaceResults()).toMatchObject([
-      { workspaceAcceptedAtMs: expect.any(Number) },
-    ]);
+    expect(placementStore.listPendingWorkspaceResults()).toEqual([]);
     expect(harness.log).toContain("placement:draining");
     expect(harness.log).toContain("workspace:resume");
   });
 
-  it("preserves a draining provider destroy failure after teardown owns the stopped tunnel", async () => {
+  it("recovers a failed provider destroy and allows a normal local reclaim", async () => {
     const harness = createTestHarness({
-      destroyFails: true,
+      destroyFailureCount: 1,
       destroyFailureState: "destroying",
       resumeFails: true,
     });
@@ -520,17 +518,18 @@ describe("worker placement dispatch", () => {
     await expect(harness.service.reclaim(REQUEST)).rejects.toThrow("destroy pending");
 
     expect(harness.environments.get(active.environmentId)).toMatchObject({
-      state: "destroying",
-      ownerEpoch: active.activeOwnerEpoch,
+      state: "destroyed",
     });
     expect(harness.placements.current()).toMatchObject({
-      state: "draining",
-      turnClaim: { owner: "worker" },
+      state: "failed",
+      turnClaim: null,
     });
-    expect(placementStore.listPendingWorkspaceResults()).toMatchObject([
-      { workspaceAcceptedAtMs: expect.any(Number) },
-    ]);
+    expect(placementStore.listPendingWorkspaceResults()).toEqual([]);
+    expect(harness.environments.destroy).toHaveBeenCalledTimes(2);
     expect(harness.log).not.toContain("workspace:resume");
+
+    await expect(harness.service.reclaim(REQUEST)).resolves.toMatchObject({ state: "local" });
+    expect(harness.environments.destroy).toHaveBeenCalledTimes(2);
   });
 
   it.each<DispatchStage>([
diff --git a/src/gateway/worker-environments/placement-dispatch.ts b/src/gateway/worker-environments/placement-dispatch.ts
index fee0758e5c4b..f225b389145e 100644
--- a/src/gateway/worker-environments/placement-dispatch.ts
+++ b/src/gateway/worker-environments/placement-dispatch.ts
@@ -548,6 +548,18 @@ export function createWorkerPlacementDispatchService(options: WorkerPlacementDis
           await cancelUnstagedFailedReclaim(
             error instanceof WorkerWorkspaceFinalFenceError && error.reclaimDisposition === "retry",
           ).catch(() => undefined);
+          const pendingReclaimResult = placements
+            .listPendingWorkspaceResults()
+            .find(
+              (pending) =>
+                pending.sessionId === reclaimClaim.sessionId &&
+                pending.claimId === reclaimClaim.claimId &&
+                pending.runId === reclaimClaim.runId,
+            );
+          if (pendingReclaimResult && pendingReclaimResult.workspaceAcceptedAtMs !== null) {
+            placements.handoffWorkspaceResultRecovery(reclaimClaim);
+            await recovery.reconcileActive(current.environmentId).catch(() => undefined);
+          }
           throw error;
         }
       },
diff --git a/src/gateway/worker-environments/placement-force-abandon.test.ts b/src/gateway/worker-environments/placement-force-abandon.test.ts
index a7c0c115dd03..2f05e232234f 100644
--- a/src/gateway/worker-environments/placement-force-abandon.test.ts
+++ b/src/gateway/worker-environments/placement-force-abandon.test.ts
@@ -87,39 +87,42 @@ describe("forced worker environment abandonment", () => {
     expect(store.listPendingWorkspaceResults()).toEqual([]);
   });
 
-  it("releases a pending worker claim when its workspace is already gone", async () => {
+  it("releases a pending reclaim claim when its workspace is already gone", async () => {
     const store = createWorkerSessionPlacementStore({ database, now: () => 1_000 });
     const { environmentId } = createDispatchEnvironmentFixtures();
     const active = seedActivePlacement(store, { environmentId, ownerEpoch: 2 });
     if (active.state !== "active") {
       throw new Error("active placement fixture was not active");
     }
-    const claim = store.claimTurn({
+    store.startDrain({
+      sessionId: active.sessionId,
+      environmentId,
+      ownerEpoch: active.activeOwnerEpoch,
+      expectedGeneration: active.generation,
+    });
+    const claim = store.claimReclaimWorkspaceResult({
       ...REQUEST,
-      claimId: "forced-missing-workspace-claim",
-      runId: "forced-missing-workspace-run",
+      claimId: "reclaim-forced-missing-workspace",
+      runId: "reclaim-forced-missing-workspace",
       owner: { kind: "worker", environmentId, ownerEpoch: 2 },
     });
-    store.markWorkspaceResultPending(claim);
     store.recordStagedWorkspaceResult(
       claim,
-      "refs/openclaw/worker-results/forced-missing-workspace-claim",
+      "refs/openclaw/worker-results/reclaim-forced-missing-workspace",
     );
-
-    await forceAbandonWorkerEnvironment({
-      placements: store,
-      environmentId,
-      resolveWorkspacePath: async () => {
-        throw new Error("session-owned managed worktree is missing");
-      },
+    const resolveWorkspacePath = vi.fn(async () => {
+      throw new Error("session-owned managed worktree is missing");
     });
 
+    await forceAbandonWorkerEnvironment({ placements: store, environmentId, resolveWorkspacePath });
+
     expect(store.get(REQUEST.sessionId)).toMatchObject({
       state: "failed",
       turnClaim: null,
       recoveryError: "Worker result abandoned by forced operator teardown",
     });
     expect(store.listPendingWorkspaceResults()).toEqual([]);
+    expect(resolveWorkspacePath).toHaveBeenCalledOnce();
   });
 
   it("deletes a stale journal without replaying it into the current workspace", async () => {
diff --git a/src/gateway/worker-environments/placement-force-abandon.ts b/src/gateway/worker-environments/placement-force-abandon.ts
index 3f224202abdd..a056acd95d91 100644
--- a/src/gateway/worker-environments/placement-force-abandon.ts
+++ b/src/gateway/worker-environments/placement-force-abandon.ts
@@ -1,5 +1,6 @@
 import type { WorkerDispatchPlacementStore } from "./placement-dispatch-failure.js";
 import { placementTurnOwner } from "./placement-record.js";
+import { isCurrentWorkerWorkspacePendingResultOwner } from "./placement-workspace-result.js";
 import { recoverWorkerWorkspaceReconciliation } from "./workspace-reconcile.js";
 import {
   deleteStagedWorkerWorkspaceResult,
@@ -98,15 +99,7 @@ export async function forceAbandonWorkerEnvironment(params: {
   for (const pending of placements.listPendingWorkspaceResults()) {
     if (pending.environmentId === environmentId) {
       const placement = placements.get(pending.sessionId);
-      if (
-        (placement?.state === "active" || placement?.state === "draining") &&
-        placement.environmentId === pending.environmentId &&
-        placement.activeOwnerEpoch === pending.ownerEpoch &&
-        placement.generation ===
-          (placement.state === "active"
-            ? pending.placementGeneration
-            : pending.placementGeneration + 1)
-      ) {
+      if (isCurrentWorkerWorkspacePendingResultOwner(placement, pending)) {
         const finalRef = pending.stagedResultRef ?? workerWorkspaceResultRef(pending.claimId);
         stagedResultCleanups.push({
           placement,
diff --git a/src/gateway/worker-environments/placement-pending-failure.ts b/src/gateway/worker-environments/placement-pending-failure.ts
index 2a48b0313897..d82adfaa7d39 100644
--- a/src/gateway/worker-environments/placement-pending-failure.ts
+++ b/src/gateway/worker-environments/placement-pending-failure.ts
@@ -1,7 +1,6 @@
 import { executeSqliteQuerySync, getNodeSqliteKysely } from "../../infra/kysely-sync.js";
 import type { DB as StateDatabase } from "../../state/openclaw-state-db.generated.js";
 import {
-  isCurrentPlacementTurnClaim,
   placementTurnOwner,
   required,
   type WorkerSessionPlacementRecord,
@@ -14,7 +13,10 @@ import {
   clearWorkerTurnToolState,
 } from "./placement-session-tool-operations.js";
 import { signalWorkerTurnClaimClosed } from "./placement-turn-claims.js";
-import type { WorkerWorkspacePendingResult } from "./placement-workspace-result.js";
+import {
+  isCurrentWorkerWorkspacePendingResultOwner,
+  type WorkerWorkspacePendingResult,
+} from "./placement-workspace-result.js";
 import { boundedWorkerError } from "./worker-error.js";
 
 export function createPlacementPendingFailureOps(runtime: PlacementStoreRuntime) {
@@ -28,6 +30,9 @@ export function createPlacementPendingFailureOps(runtime: PlacementStoreRuntime)
       const recoveryError = boundedWorkerError(error);
       const outcome = write((db) => {
         const current = getRequired(db, sessionId);
+        if (!isCurrentWorkerWorkspacePendingResultOwner(current, pending)) {
+          throw new Error(`Session ${sessionId} workspace result owner changed before failure`);
+        }
         const persisted = current.turnClaim;
         const releasedClaim: WorkerSessionTurnClaim | null = persisted
           ? {
@@ -35,31 +40,9 @@ export function createPlacementPendingFailureOps(runtime: PlacementStoreRuntime)
               claimId: persisted.claimId,
               runId: persisted.runId,
               placementGeneration: persisted.generation,
-              owner: placementTurnOwner({
-                executionMode: current.executionMode,
-                environmentId: pending.environmentId,
-                activeOwnerEpoch: pending.ownerEpoch,
-              }),
+              owner: placementTurnOwner(current),
             }
           : null;
-        const exactClaim =
-          releasedClaim === null ||
-          (releasedClaim.claimId === pending.claimId &&
-            releasedClaim.runId === pending.runId &&
-            releasedClaim.placementGeneration === pending.placementGeneration &&
-            isCurrentPlacementTurnClaim(current, releasedClaim));
-        if (
-          (current.state !== "active" && current.state !== "draining") ||
-          current.environmentId !== pending.environmentId ||
-          current.activeOwnerEpoch !== pending.ownerEpoch ||
-          current.generation !==
-            (current.state === "active"
-              ? pending.placementGeneration
-              : pending.placementGeneration + 1) ||
-          !exactClaim
-        ) {
-          throw new Error(`Session ${sessionId} workspace result owner changed before failure`);
-        }
         const pendingQuery =
           getNodeSqliteKysely<Pick<StateDatabase, "worker_workspace_pending_results">>(db);
         const exactPending = executeSqliteQuerySync(
diff --git a/src/gateway/worker-environments/placement-workspace-result.ts b/src/gateway/worker-environments/placement-workspace-result.ts
index c6958e683711..5532f42f4183 100644
--- a/src/gateway/worker-environments/placement-workspace-result.ts
+++ b/src/gateway/worker-environments/placement-workspace-result.ts
@@ -32,6 +32,35 @@ export type WorkerWorkspacePendingResult = {
   stagedResultRef: string | null;
 };
 
+export function isCurrentWorkerWorkspacePendingResultOwner(
+  placement: WorkerSessionPlacementRecord | undefined,
+  pending: WorkerWorkspacePendingResult,
+): placement is Extract<WorkerSessionPlacementRecord, { state: "active" | "draining" }> {
+  if (
+    (placement?.state !== "active" && placement?.state !== "draining") ||
+    placement.sessionId !== pending.sessionId ||
+    placement.environmentId !== pending.environmentId ||
+    placement.activeOwnerEpoch !== pending.ownerEpoch
+  ) {
+    return false;
+  }
+  if (placement.turnClaim) {
+    // Reclaim claims after drain; worker turns claim before it. The exact live
+    // claim owns either generation shape without weakening claimless recovery.
+    return isCurrentPlacementTurnClaim(placement, {
+      sessionId: pending.sessionId,
+      claimId: pending.claimId,
+      runId: pending.runId,
+      placementGeneration: pending.placementGeneration,
+      owner: placementTurnOwner(placement),
+    });
+  }
+  return (
+    placement.generation ===
+    (placement.state === "active" ? pending.placementGeneration : pending.placementGeneration + 1)
+  );
+}
+
 function matchesWorkspaceResultClaim(
   placement: WorkerSessionPlacementRecord,
   row: StateDatabase["worker_workspace_pending_results"],

From 1257279de6cf8829a505e9e565a9656ee1268ecd Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 15:40:50 -0700
Subject: [PATCH 118/124] fix(macos): suppress SIGPIPE on process pipe write
 ends (#127666)

Writing to a pipe whose reader has already exited raises SIGPIPE, which
kills the whole process instead of throwing. MacNodeHostWorker already
guarded its stdin pipe with F_SETNOSIGPIPE; the codex App Server client
and the MLX TTS helper transport did not, so a child exiting mid-write
could take down the app. Suppressing the signal exposed that an
undelivered App Server request write was reported as appServerUnavailable
even though the frame was provably never sent, so it now requeues once
onto a fresh child instead of failing the caller.

Test-side pipe write ends whose readers are spawned children (or a
readability handler that can close the pipe mid-test) get the same
suppression so a racing reader exit fails the assertion instead of
killing swiftpm-testing-helper with signal 13, which is what caused the
macos-swift CI lane's intermittent unrelated-test crashes (e.g. PR
#126559, run 32341197738 job 96340683947).
---
 .../OpenClaw/FileHandle+SafeRead.swift        |  9 ++++++++
 .../MacNodeCodexThreadCatalogClient.swift     | 22 ++++++++++++++++---
 .../OpenClaw/NodeMode/MacNodeHostWorker.swift |  2 +-
 .../OpenClaw/TalkMLXSpeechSynthesizer.swift   |  3 +++
 .../CuaDriverHostCoordinatorTests.swift       |  4 ++++
 .../MacNodeCodexThreadCatalogTests.swift      |  6 ++++-
 .../OpenClawIPCTests/TestProcessSupport.swift | 10 +++++++++
 .../TestProcessSupportPipeTests.swift         | 17 ++++++++++++++
 8 files changed, 68 insertions(+), 5 deletions(-)
 create mode 100644 apps/macos/Tests/OpenClawIPCTests/TestProcessSupportPipeTests.swift

diff --git a/apps/macos/Sources/OpenClaw/FileHandle+SafeRead.swift b/apps/macos/Sources/OpenClaw/FileHandle+SafeRead.swift
index 7cd160969389..50e5e18ff3f2 100644
--- a/apps/macos/Sources/OpenClaw/FileHandle+SafeRead.swift
+++ b/apps/macos/Sources/OpenClaw/FileHandle+SafeRead.swift
@@ -1,6 +1,15 @@
+import Darwin
 import Foundation
 
 extension FileHandle {
+    /// Marks a pipe/socket write end so a vanished reader fails the write with a
+    /// thrown EPIPE instead of raising SIGPIPE, which kills the whole process.
+    /// Required on every write end whose reader is another process that can exit.
+    @discardableResult
+    func disableSIGPIPE() -> Bool {
+        fcntl(self.fileDescriptor, F_SETNOSIGPIPE, 1) != -1
+    }
+
     /// Reads until EOF using the throwing FileHandle API and returns empty `Data` on failure.
     ///
     /// Important: Avoid legacy, non-throwing FileHandle read APIs (e.g. `readDataToEndOfFile()` and
diff --git a/apps/macos/Sources/OpenClaw/NodeMode/MacNodeCodexThreadCatalogClient.swift b/apps/macos/Sources/OpenClaw/NodeMode/MacNodeCodexThreadCatalogClient.swift
index b1a557d36867..bd18a436471f 100644
--- a/apps/macos/Sources/OpenClaw/NodeMode/MacNodeCodexThreadCatalogClient.swift
+++ b/apps/macos/Sources/OpenClaw/NodeMode/MacNodeCodexThreadCatalogClient.swift
@@ -62,6 +62,9 @@ final class CodexAppServerThreadClient: @unchecked Sendable {
         var requestData: Data?
         var continuation: CheckedContinuation<Data, Error>?
         var timer: DispatchSourceTimer?
+        /// One requeue budget for the child-exit race: a failed stdin write was
+        /// never delivered, so a single retry on a fresh child cannot duplicate.
+        var redelivered = false
 
         init(
             token: UUID,
@@ -105,6 +108,9 @@ final class CodexAppServerThreadClient: @unchecked Sendable {
         {
             self.invocation = invocation
             self.initializeRequestID = initializeRequestID
+            // The App Server child can exit between requests; without this an
+            // in-flight stdin write raises SIGPIPE and kills the app.
+            self.stdinPipe.fileHandleForWriting.disableSIGPIPE()
         }
     }
 
@@ -351,9 +357,19 @@ final class CodexAppServerThreadClient: @unchecked Sendable {
             }
             try self.write(requestData, over: connection)
         } catch {
-            self.finishActive(
-                .failure(MacNodeCodexThreadCatalog.CatalogError.appServerUnavailable),
-                restartConnection: true)
+            // A warm connection can outlive its child; the exit race surfaces
+            // here as EPIPE before termination is observed. The frame was never
+            // delivered, so requeue once onto a fresh child instead of failing.
+            guard !active.redelivered else {
+                self.finishActive(
+                    .failure(MacNodeCodexThreadCatalog.CatalogError.appServerUnavailable),
+                    restartConnection: true)
+                return
+            }
+            active.redelivered = true
+            self.active = nil
+            self.pending.insert(active, at: 0)
+            self.stopConnection(abortive: true)
         }
     }
 
diff --git a/apps/macos/Sources/OpenClaw/NodeMode/MacNodeHostWorker.swift b/apps/macos/Sources/OpenClaw/NodeMode/MacNodeHostWorker.swift
index b77bd312f6d1..7eb5997352d2 100644
--- a/apps/macos/Sources/OpenClaw/NodeMode/MacNodeHostWorker.swift
+++ b/apps/macos/Sources/OpenClaw/NodeMode/MacNodeHostWorker.swift
@@ -350,7 +350,7 @@ final class MacNodeHostWorker: MacNodeHostWorking, @unchecked Sendable {
         let stdinPipe = Pipe()
         let stdoutPipe = Pipe()
         let stderrPipe = Pipe()
-        guard fcntl(stdinPipe.fileHandleForWriting.fileDescriptor, F_SETNOSIGPIPE, 1) != -1 else {
+        guard stdinPipe.fileHandleForWriting.disableSIGPIPE() else {
             self.finishStartLocked(.failure(WorkerError.unavailable("could not protect worker input pipe")))
             return
         }
diff --git a/apps/macos/Sources/OpenClaw/TalkMLXSpeechSynthesizer.swift b/apps/macos/Sources/OpenClaw/TalkMLXSpeechSynthesizer.swift
index 4b0887b78198..9068691dd369 100644
--- a/apps/macos/Sources/OpenClaw/TalkMLXSpeechSynthesizer.swift
+++ b/apps/macos/Sources/OpenClaw/TalkMLXSpeechSynthesizer.swift
@@ -642,6 +642,9 @@ private actor ProcessMLXTTSTransport: MLXTTSTransport {
     {
         let inputPipe = Pipe()
         let outputPipe = Pipe()
+        // The helper child can exit at any time; without this a racing
+        // send() to its stdin raises SIGPIPE and kills the app.
+        inputPipe.fileHandleForWriting.disableSIGPIPE()
 
         let output = outputPipe.fileHandleForReading
         let (stream, continuation) = AsyncStream<Data>.makeStream()
diff --git a/apps/macos/Tests/OpenClawIPCTests/CuaDriverHostCoordinatorTests.swift b/apps/macos/Tests/OpenClawIPCTests/CuaDriverHostCoordinatorTests.swift
index fe23638c0862..02deb9e5b5a8 100644
--- a/apps/macos/Tests/OpenClawIPCTests/CuaDriverHostCoordinatorTests.swift
+++ b/apps/macos/Tests/OpenClawIPCTests/CuaDriverHostCoordinatorTests.swift
@@ -423,6 +423,10 @@ struct CuaDriverHostCoordinatorTests {
         driver diagnostic
 
         """
+        // The relay's readability handler calls stop() on any empty read, which
+        // closes the pipe's read end; without suppression a racing stop turns
+        // this write into a harness-killing SIGPIPE.
+        try TestProcessSupport.suppressSIGPIPE(relay.pipe.fileHandleForWriting)
         try relay.pipe.fileHandleForWriting.write(contentsOf: Data(driverOutput.utf8))
         try relay.pipe.fileHandleForWriting.close()
         for _ in 0..<1000 where probe.events.count < 2 {
diff --git a/apps/macos/Tests/OpenClawIPCTests/MacNodeCodexThreadCatalogTests.swift b/apps/macos/Tests/OpenClawIPCTests/MacNodeCodexThreadCatalogTests.swift
index c5722c1e9a7a..dc8b1ecc64fd 100644
--- a/apps/macos/Tests/OpenClawIPCTests/MacNodeCodexThreadCatalogTests.swift
+++ b/apps/macos/Tests/OpenClawIPCTests/MacNodeCodexThreadCatalogTests.swift
@@ -197,9 +197,13 @@ struct MacNodeCodexThreadCatalogTests {
     }
 
     private func openFIFOForWriting(_ url: URL) async throws -> FileHandle {
-        try await Task.detached {
+        let handle = try await Task.detached {
             try FileHandle(forWritingTo: url)
         }.value
+        // The FIFO reader is a spawned fake child; if it exits before the exit
+        // gate write, an unsuppressed SIGPIPE kills the whole test harness.
+        try TestProcessSupport.suppressSIGPIPE(handle)
+        return handle
     }
 
     private func requestEmptyList(
diff --git a/apps/macos/Tests/OpenClawIPCTests/TestProcessSupport.swift b/apps/macos/Tests/OpenClawIPCTests/TestProcessSupport.swift
index cd603b75580e..cdec3e98746a 100644
--- a/apps/macos/Tests/OpenClawIPCTests/TestProcessSupport.swift
+++ b/apps/macos/Tests/OpenClawIPCTests/TestProcessSupport.swift
@@ -1,6 +1,7 @@
 import Darwin
 import Foundation
 import Testing
+@testable import OpenClaw
 
 enum TestProcessSupport {
     static func pollPID(in file: URL) -> pid_t? {
@@ -34,6 +35,15 @@ enum TestProcessSupport {
         return self.processIsGone(pid)
     }
 
+    /// SIGPIPE from a write whose reader already exited kills the entire test
+    /// process (swiftpm-testing-helper dies with signal 13, blaming whatever
+    /// test happens to be running). Mirror the production F_SETNOSIGPIPE guard
+    /// (MacNodeHostWorker) so a racing reader exit surfaces as a thrown EPIPE
+    /// on that one write instead.
+    static func suppressSIGPIPE(_ writeEnd: FileHandle) throws {
+        try #require(writeEnd.disableSIGPIPE())
+    }
+
     static func killLeakedProcesses(in files: [URL]) {
         let pids = files.compactMap { self.pollPID(in: $0) }
         for pid in pids where !self.processIsGone(pid) {
diff --git a/apps/macos/Tests/OpenClawIPCTests/TestProcessSupportPipeTests.swift b/apps/macos/Tests/OpenClawIPCTests/TestProcessSupportPipeTests.swift
new file mode 100644
index 000000000000..d3ab80e756a7
--- /dev/null
+++ b/apps/macos/Tests/OpenClawIPCTests/TestProcessSupportPipeTests.swift
@@ -0,0 +1,17 @@
+import Foundation
+import Testing
+
+struct TestProcessSupportPipeTests {
+    @Test func `suppressed write end reports EPIPE instead of killing the harness`() throws {
+        let pipe = Pipe()
+        try TestProcessSupport.suppressSIGPIPE(pipe.fileHandleForWriting)
+        try pipe.fileHandleForReading.close()
+
+        // Without suppression this write would raise SIGPIPE and take down the
+        // whole swiftpm-testing-helper process instead of throwing.
+        #expect(throws: Error.self) {
+            try pipe.fileHandleForWriting.write(contentsOf: Data("x".utf8))
+        }
+        try pipe.fileHandleForWriting.close()
+    }
+}

From ee468b80388b34f44fc5cfb01e8d9c78c66b731a Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 15:42:39 -0700
Subject: [PATCH 119/124] fix(macos): prevent stale port sweeps from killing
 remote tunnels (#127665)

---
 .../OpenClaw/ConnectionModeCoordinator.swift  |  4 ++-
 apps/macos/Sources/OpenClaw/MenuBar.swift     |  2 +-
 .../macos/Sources/OpenClaw/PortGuardian.swift | 10 ++++--
 .../PortGuardianRecordStoreTests.swift        | 36 +++++++++++++++++++
 4 files changed, 48 insertions(+), 4 deletions(-)

diff --git a/apps/macos/Sources/OpenClaw/ConnectionModeCoordinator.swift b/apps/macos/Sources/OpenClaw/ConnectionModeCoordinator.swift
index fe576b5a079b..1362a9e901a3 100644
--- a/apps/macos/Sources/OpenClaw/ConnectionModeCoordinator.swift
+++ b/apps/macos/Sources/OpenClaw/ConnectionModeCoordinator.swift
@@ -22,10 +22,12 @@ final class ConnectionModeCoordinator {
 
     private let logger = Logger(subsystem: "ai.openclaw", category: "connection")
     private var transition = Transition()
+    private var portSweepTask: Task<Void, Never>?
 
     /// Apply the requested connection mode by starting/stopping local gateway,
     /// managing the control-channel SSH tunnel, and cleaning up chat windows/panels.
     func apply(mode: AppState.ConnectionMode, paused: Bool) async {
+        self.portSweepTask?.cancel()
         let previousMode = self.transition.mode
         let applyGeneration = self.transition.begin(mode)
         if let previousMode, previousMode != mode {
@@ -76,7 +78,7 @@ final class ConnectionModeCoordinator {
             }
         }
 
-        Task.detached { await PortGuardian.shared.sweep(mode: mode) }
+        self.portSweepTask = Task { await PortGuardian.shared.sweep(mode: mode) }
     }
 
     private func applyLocalMode(paused: Bool, generation: UInt64) async {
diff --git a/apps/macos/Sources/OpenClaw/MenuBar.swift b/apps/macos/Sources/OpenClaw/MenuBar.swift
index afef64db02c2..26c3bc7d142b 100644
--- a/apps/macos/Sources/OpenClaw/MenuBar.swift
+++ b/apps/macos/Sources/OpenClaw/MenuBar.swift
@@ -652,7 +652,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
         }
         Task { PresenceReporter.shared.start() }
         Task { await HealthStore.shared.refresh(onDemand: true) }
-        Task { await PortGuardian.shared.sweep(mode: AppStateStore.shared.connectionMode) }
+        Task { await PortGuardian.shared.reapOrphanedTunnels() }
         AppStateStore.shared.applyComputerControlHostState()
         if launchPlan.allowsAutomaticPresentation {
             DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) {
diff --git a/apps/macos/Sources/OpenClaw/PortGuardian.swift b/apps/macos/Sources/OpenClaw/PortGuardian.swift
index f0c3002df196..d2ca2c3f1d55 100644
--- a/apps/macos/Sources/OpenClaw/PortGuardian.swift
+++ b/apps/macos/Sources/OpenClaw/PortGuardian.swift
@@ -60,10 +60,12 @@ actor PortGuardian {
     }
 
     func sweep(mode: AppState.ConnectionMode) async {
+        guard !Task.isCancelled else { return }
         self.logger.info("port sweep starting (mode=\(mode.rawValue, privacy: .public))")
         // Reap before the port scan and in every mode: orphans come from earlier
         // remote sessions and must die even after the user switched modes.
         await self.reapOrphanedTunnels()
+        guard !Task.isCancelled else { return }
         guard mode != .unconfigured else {
             self.logger.info("port sweep skipped (mode=unconfigured)")
             return
@@ -72,9 +74,11 @@ actor PortGuardian {
         // Capture the listener before launchd status. If its process exits and the
         // PID is reused, the newer status snapshot cannot bless the replacement.
         let listeners = await self.listeners(on: port)
+        guard !Task.isCancelled else { return }
         let managedGatewayPID = mode == .local
             ? await GatewayLaunchAgentManager.runningGatewayPID()
             : nil
+        guard !Task.isCancelled else { return }
         for listener in listeners {
             if Self.isExpected(
                 listener,
@@ -103,6 +107,7 @@ actor PortGuardian {
                         "(pid \(listener.pid, privacy: .public)); preserving conflict")
                 continue
             }
+            guard !Task.isCancelled else { return }
             if await Self.terminateProcess(listener.pid) {
                 let message = """
                 port \(port) was held by \(listener.command)
@@ -330,9 +335,10 @@ actor PortGuardian {
     /// forget a still-running tunnel (the record is its only retry path).
     private static func terminateProcess(_ pid: Int32) async -> Bool {
         #if canImport(Darwin)
-        guard pid > 0 else { return false }
+        guard !Task.isCancelled, pid > 0 else { return false }
         _ = Darwin.kill(pid, SIGTERM)
         if await self.waitForProcessExit(pid: pid) { return true }
+        guard !Task.isCancelled else { return false }
         _ = Darwin.kill(pid, SIGKILL)
         return await self.waitForProcessExit(pid: pid)
         #else
@@ -343,7 +349,7 @@ actor PortGuardian {
     private static func waitForProcessExit(pid: Int32, timeout: TimeInterval = 1.0) async -> Bool {
         let deadline = Date().addingTimeInterval(timeout)
         while self.tunnelProcessInfo(pid: pid) != nil {
-            guard Date() < deadline else { return false }
+            guard !Task.isCancelled, Date() < deadline else { return false }
             try? await Task.sleep(nanoseconds: 50_000_000)
         }
         return true
diff --git a/apps/macos/Tests/OpenClawIPCTests/PortGuardianRecordStoreTests.swift b/apps/macos/Tests/OpenClawIPCTests/PortGuardianRecordStoreTests.swift
index f85295ed9cad..22eb0b326c6c 100644
--- a/apps/macos/Tests/OpenClawIPCTests/PortGuardianRecordStoreTests.swift
+++ b/apps/macos/Tests/OpenClawIPCTests/PortGuardianRecordStoreTests.swift
@@ -122,6 +122,42 @@ struct PortGuardianRecordStoreTests {
         #expect(try store.records().isEmpty)
     }
 
+    @Test
+    func `cancelled port sweep never touches its durable tunnel records`() async throws {
+        let fixture = try Self.fixture()
+        defer { fixture.cleanup() }
+        let store = try PortGuardianRecordStore(databaseURL: fixture.databaseURL)
+        let orphan = Self.record(pid: 2_000_000_000, port: 18789, timestamp: 1)
+        try store.upsert(orphan)
+        let guardian = PortGuardian(recordStoreFactory: {
+            try PortGuardianRecordStore(databaseURL: fixture.databaseURL)
+        })
+
+        let sweep = Task {
+            withUnsafeCurrentTask { $0?.cancel() }
+            await guardian.sweep(mode: .unconfigured)
+        }
+        await sweep.value
+
+        #expect(try store.records() == [orphan])
+    }
+
+    @Test
+    func `uncancelled unconfigured sweep still reaps orphaned tunnel records`() async throws {
+        let fixture = try Self.fixture()
+        defer { fixture.cleanup() }
+        let store = try PortGuardianRecordStore(databaseURL: fixture.databaseURL)
+        let orphan = Self.record(pid: 2_000_000_000, port: 18789, timestamp: 1)
+        try store.upsert(orphan)
+        let guardian = PortGuardian(recordStoreFactory: {
+            try PortGuardianRecordStore(databaseURL: fixture.databaseURL)
+        })
+
+        await guardian.sweep(mode: .unconfigured)
+
+        #expect(try store.records().isEmpty)
+    }
+
     @Test
     func `failed receipt deletion relinquishes ownership for sweep retry`() async throws {
         let fixture = try Self.fixture()

From 74c1900e630f241b8b9a9dc93c56556bc06bf0da Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 15:43:39 -0700
Subject: [PATCH 120/124] refactor(tooling): unify managed child process
 cleanup (#127480)

---
 scripts/bench-cli-startup.ts                  |  76 +++----
 scripts/dev/tui-pty-test-watch.ts             |  75 +------
 scripts/e2e/parallels/host-command.ts         | 105 ++++-----
 .../lib/cross-os-release-checks/process.ts    |  16 +-
 scripts/lib/gateway-bench-child.ts            | 117 ++++------
 scripts/lib/managed-child-process.mts         | 201 +++++++++++++-----
 scripts/run-additional-boundary-checks.mts    |  42 ++--
 scripts/run-oxlint-shards.mts                 |  90 +++-----
 scripts/test-docker-all.mts                   |  48 ++---
 scripts/test-group-report.mts                 | 107 ++--------
 scripts/tsdown-build.mts                      |  48 ++---
 .../bench-gateway-child-test-support.ts       | 118 ----------
 test/scripts/dev-tooling-safety.test.ts       |  94 --------
 test/scripts/docker-all-scheduler.test.ts     |   2 +
 test/scripts/managed-child-process.test.ts    | 141 ++++++++++++
 test/scripts/test-group-report.test.ts        |  75 -------
 16 files changed, 514 insertions(+), 841 deletions(-)

diff --git a/scripts/bench-cli-startup.ts b/scripts/bench-cli-startup.ts
index c7b950a7e720..a1620e4eec67 100644
--- a/scripts/bench-cli-startup.ts
+++ b/scripts/bench-cli-startup.ts
@@ -5,6 +5,11 @@ import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { expectDefined } from "../packages/normalization-core/src/expect.js";
+import {
+  inspectManagedProcessGroup,
+  terminateManagedChild,
+  waitForManagedProcessGroupExit,
+} from "./lib/managed-child-process.mts";
 
 type CommandCase = {
   id: string;
@@ -116,7 +121,6 @@ const DEFAULT_WARMUP = 1;
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_TIMEOUT_KILL_GRACE_MS = 1_000;
 const TIMEOUT_KILL_GRACE_MS = resolveTimeoutKillGraceMs(process.env);
-const PROCESS_GROUP_EXIT_POLL_MS = 25;
 const DEFAULT_ENTRY = "openclaw.mjs";
 const MAX_RSS_MARKER = "__OPENCLAW_MAX_RSS_KB__=";
 
@@ -799,10 +803,9 @@ async function runSample(params: {
 
   try {
     return await new Promise<Sample>((resolve) => {
-      const useProcessGroup = process.platform !== "win32";
       const proc = spawn(process.execPath, nodeArgs, {
         cwd: process.cwd(),
-        detached: useProcessGroup,
+        detached: process.platform !== "win32",
         env: {
           ...process.env,
           HOME: runRoot,
@@ -846,10 +849,10 @@ async function runSample(params: {
 
       const timeout = setTimeout(() => {
         timedOut = true;
-        signalSampleProcess(proc, "SIGTERM", useProcessGroup);
+        signalSampleProcess(proc, "SIGTERM");
         forceKillAt = Date.now() + TIMEOUT_KILL_GRACE_MS;
         forceKillTimer = setTimeout(() => {
-          signalSampleProcess(proc, "SIGKILL", useProcessGroup);
+          signalSampleProcess(proc, "SIGKILL");
         }, TIMEOUT_KILL_GRACE_MS).unref?.();
       }, params.timeoutMs);
       timeout.unref?.();
@@ -889,12 +892,11 @@ async function runSample(params: {
                   stderrTail: tailLines(stderr, 20),
                 }),
           });
-        if (timedOut && isSampleProcessGroupAlive(proc, useProcessGroup)) {
+        if (timedOut && isSampleProcessGroupAlive(proc)) {
           void finishAfterTimeoutCleanup({
             complete,
             forceKillAt,
             proc,
-            useProcessGroup,
           });
           return;
         }
@@ -912,74 +914,48 @@ async function finishAfterTimeoutCleanup(params: {
   complete: () => void;
   forceKillAt: number | null;
   proc: ReturnType<typeof spawn>;
-  useProcessGroup: boolean;
 }): Promise<void> {
   const graceRemainingMs =
     params.forceKillAt === null
       ? TIMEOUT_KILL_GRACE_MS
       : Math.max(0, params.forceKillAt - Date.now());
   if (graceRemainingMs > 0) {
-    await waitForSampleProcessGroupExit(params.proc, params.useProcessGroup, graceRemainingMs);
+    await waitForSampleProcessGroupExit(params.proc, graceRemainingMs);
   }
-  if (isSampleProcessGroupAlive(params.proc, params.useProcessGroup)) {
-    signalSampleProcess(params.proc, "SIGKILL", params.useProcessGroup);
+  if (isSampleProcessGroupAlive(params.proc)) {
+    signalSampleProcess(params.proc, "SIGKILL");
   }
-  await waitForSampleProcessGroupExit(params.proc, params.useProcessGroup, TIMEOUT_KILL_GRACE_MS);
+  await waitForSampleProcessGroupExit(params.proc, TIMEOUT_KILL_GRACE_MS);
   params.complete();
 }
 
-function signalSampleProcess(
-  proc: ReturnType<typeof spawn>,
-  signal: NodeJS.Signals,
-  useProcessGroup: boolean,
-): void {
+function signalSampleProcess(proc: ReturnType<typeof spawn>, signal: NodeJS.Signals): void {
   if (!proc.pid) {
     return;
   }
-  try {
-    if (useProcessGroup) {
-      process.kill(-proc.pid, signal);
-    } else {
-      proc.kill(signal);
-    }
-  } catch (error) {
+  const handleSignalError = (error: unknown) => {
     const code = (error as NodeJS.ErrnoException | undefined)?.code;
     if (code !== "ESRCH" && code !== "EPERM") {
       throw error;
     }
-  }
+  };
+  terminateManagedChild(proc, signal, {
+    onChildSignalError: handleSignalError,
+    onProcessGroupSignalError: handleSignalError,
+    processGroupFallback: "never",
+    useWindowsTaskkill: false,
+  });
 }
 
-function isSampleProcessGroupAlive(
-  proc: ReturnType<typeof spawn>,
-  useProcessGroup: boolean,
-): boolean {
-  if (!useProcessGroup || !proc.pid) {
-    return false;
-  }
-  try {
-    process.kill(-proc.pid, 0);
-    return true;
-  } catch (error) {
-    return (error as NodeJS.ErrnoException | undefined)?.code === "EPERM";
-  }
+function isSampleProcessGroupAlive(proc: ReturnType<typeof spawn>): boolean {
+  return inspectManagedProcessGroup(proc, { errorPolicy: "alive-on-eperm" }) === "live";
 }
 
-async function waitForSampleProcessGroupExit(
+function waitForSampleProcessGroupExit(
   proc: ReturnType<typeof spawn>,
-  useProcessGroup: boolean,
   timeoutMs: number,
 ): Promise<boolean> {
-  const deadlineAt = Date.now() + timeoutMs;
-  while (Date.now() < deadlineAt) {
-    if (!isSampleProcessGroupAlive(proc, useProcessGroup)) {
-      return true;
-    }
-    await new Promise((resolvePoll) => {
-      setTimeout(resolvePoll, PROCESS_GROUP_EXIT_POLL_MS);
-    });
-  }
-  return !isSampleProcessGroupAlive(proc, useProcessGroup);
+  return waitForManagedProcessGroupExit(proc, timeoutMs, { errorPolicy: "alive-on-eperm" });
 }
 
 async function runCase(params: {
diff --git a/scripts/dev/tui-pty-test-watch.ts b/scripts/dev/tui-pty-test-watch.ts
index 08d0acddfc25..b16577aed8a7 100644
--- a/scripts/dev/tui-pty-test-watch.ts
+++ b/scripts/dev/tui-pty-test-watch.ts
@@ -1,11 +1,11 @@
 // Tui Pty Test Watch script supports OpenClaw repository automation.
-import { spawn, spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { mkdir, open, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { terminateManagedChild } from "../lib/managed-child-process.mts";
 import { sleep as delay } from "../lib/sleep.mjs";
-import { resolveWindowsTaskkillPath } from "../lib/windows-taskkill.mjs";
 
 type Options = {
   altScreen: boolean;
@@ -48,12 +48,6 @@ type ChildStopper = {
 
 type SignalChild = (child: KillableChild, signal: NodeJS.Signals) => void;
 
-type RunTaskkill = (
-  command: string,
-  args: string[],
-  options: { stdio: "ignore" },
-) => { error?: unknown; status?: number | null } | undefined;
-
 function unrefTimer(timer: ReturnType<typeof setTimeout>): void {
   (timer as { unref?: () => void }).unref?.();
 }
@@ -133,60 +127,6 @@ function currentTerminalDimension(value: number | undefined, fallback: number):
   return String(value && value > 0 ? value : fallback);
 }
 
-function signalWindowsProcessTree(
-  pid: number,
-  signal: NodeJS.Signals,
-  runTaskkill: RunTaskkill = spawnSync,
-): boolean {
-  const args = ["/PID", String(pid), "/T"];
-  if (signal === "SIGKILL") {
-    args.push("/F");
-  }
-  const result = runTaskkill(resolveWindowsTaskkillPath(), args, { stdio: "ignore" });
-  return !result?.error && result?.status === 0;
-}
-
-function signalWindowsProcessTreeOrForce(
-  pid: number,
-  signal: NodeJS.Signals,
-  runTaskkill: RunTaskkill = spawnSync,
-): boolean {
-  if (signalWindowsProcessTree(pid, signal, runTaskkill)) {
-    return true;
-  }
-  return signal !== "SIGKILL" && signalWindowsProcessTree(pid, "SIGKILL", runTaskkill);
-}
-
-function signalChildProcessTree(
-  child: KillableChild,
-  signal: NodeJS.Signals,
-  {
-    platform = process.platform,
-    runTaskkill = spawnSync,
-    useProcessGroup = platform !== "win32",
-  }: {
-    platform?: NodeJS.Platform;
-    runTaskkill?: RunTaskkill;
-    useProcessGroup?: boolean;
-  } = {},
-): void {
-  if (useProcessGroup && typeof child.pid === "number") {
-    try {
-      process.kill(-child.pid, signal);
-      return;
-    } catch {
-      // Non-detached fallback or already-exited group; direct child signaling is
-      // still useful on platforms without process groups.
-    }
-  }
-  if (platform === "win32" && typeof child.pid === "number") {
-    if (signalWindowsProcessTreeOrForce(child.pid, signal, runTaskkill)) {
-      return;
-    }
-  }
-  child.kill(signal);
-}
-
 function createChildStopper(
   child: KillableChild,
   options: {
@@ -195,7 +135,15 @@ function createChildStopper(
     sigkillGraceMs?: number;
   } = {},
 ): ChildStopper {
-  const signalChild = options.signalChild ?? signalChildProcessTree;
+  const signalChild =
+    options.signalChild ??
+    ((targetChild, signal) =>
+      terminateManagedChild(targetChild, signal, {
+        onChildSignalError(error) {
+          throw error;
+        },
+        taskkillTimeoutMs: null,
+      }));
   const sigtermGraceMs = options.sigtermGraceMs ?? CHILD_SIGTERM_GRACE_MS;
   const sigkillGraceMs = options.sigkillGraceMs ?? CHILD_SIGKILL_GRACE_MS;
   let stopping = false;
@@ -523,5 +471,4 @@ export const testing = {
   drainNewMirrorData,
   parseOptions,
   readNewMirrorData,
-  signalChildProcessTree,
 };
diff --git a/scripts/e2e/parallels/host-command.ts b/scripts/e2e/parallels/host-command.ts
index 8823d6f3b653..ef1738cfa5ed 100644
--- a/scripts/e2e/parallels/host-command.ts
+++ b/scripts/e2e/parallels/host-command.ts
@@ -8,6 +8,11 @@ import {
   addTimerTimeoutGraceMs,
   clampTimerTimeoutMs,
 } from "@openclaw/normalization-core/number-coercion";
+import {
+  inspectManagedProcessGroup,
+  terminateManagedChild,
+  waitForManagedProcessGroupExit,
+} from "../../lib/managed-child-process.mts";
 import { resolveNpmRunner } from "../../npm-runner.mts";
 import { resolvePnpmRunner } from "../../pnpm-runner.mts";
 import { buildCmdExeCommandLine, resolveWindowsCmdExePath } from "../../windows-cmd-helpers.mjs";
@@ -20,7 +25,6 @@ const HOST_COMMAND_WRAPPER_EXTRA_BUFFER_BYTES = 1024 * 1024;
 const HOST_COMMAND_WRAPPER_BACKSTOP_MS = 5_000;
 const HOST_COMMAND_TIMEOUT_KILL_GRACE_MS = 100;
 const HOST_COMMAND_STREAMING_TIMEOUT_KILL_GRACE_MS = 2_000;
-const HOST_COMMAND_PROCESS_GROUP_EXIT_POLL_MS = 25;
 const HOST_COMMAND_POST_FORCE_KILL_WAIT_MS = 100;
 const HOST_COMMAND_CHILD_PID_PREFIX = "__OPENCLAW_HOST_COMMAND_CHILD_PID__";
 const HOST_COMMAND_SPAWN_ERROR_PREFIX = "__OPENCLAW_HOST_COMMAND_SPAWN_ERROR__";
@@ -79,36 +83,31 @@ function signalHostCommandProcess(pid: number | undefined, signal: NodeJS.Signal
   if (!pid) {
     return;
   }
-  if (process.platform === "win32") {
-    try {
-      process.kill(pid, signal);
-    } catch (error) {
-      const code = (error as NodeJS.ErrnoException).code;
-      if (code !== "ESRCH") {
-        warn(`failed to send ${signal} to host command process ${pid}: ${code ?? String(error)}`);
-      }
-    }
-    return;
-  }
-  try {
-    process.kill(-pid, signal);
-  } catch (error) {
-    const code = (error as NodeJS.ErrnoException).code;
-    if (code === "ESRCH") {
-      return;
-    }
-    try {
-      process.kill(pid, signal);
-    } catch (fallbackError) {
-      const fallbackCode = (fallbackError as NodeJS.ErrnoException).code;
-      if (fallbackCode === "ESRCH") {
-        return;
-      }
-      warn(
-        `failed to send ${signal} to host command process ${pid}: group ${code ?? String(error)}, leader ${fallbackCode ?? String(fallbackError)}`,
-      );
-    }
-  }
+  let processGroupError: NodeJS.ErrnoException | undefined;
+  terminateManagedChild(
+    {
+      kill: (childSignal) => process.kill(pid, childSignal),
+      pid,
+    },
+    signal,
+    {
+      onChildSignalError(error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code === "ESRCH") {
+          return;
+        }
+        const reason = processGroupError
+          ? `group ${processGroupError.code ?? processGroupError.toString()}, leader ${code ?? String(error)}`
+          : (code ?? String(error));
+        warn(`failed to send ${signal} to host command process ${pid}: ${reason}`);
+      },
+      onProcessGroupSignalError(error) {
+        processGroupError = error as NodeJS.ErrnoException;
+      },
+      processGroupFallback: "nonmissing",
+      useWindowsTaskkill: false,
+    },
+  );
 }
 
 const POSIX_TIMEOUT_WRAPPER = String.raw`
@@ -604,40 +603,16 @@ export async function runStreaming(
         }
       }
     };
-    const streamingProcessGroupAlive = (): boolean => {
-      if (!detached || !childPid) {
-        return false;
-      }
-      try {
-        process.kill(-childPid, 0);
-        return true;
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== "EPERM") {
-          return false;
-        }
-        if (child.exitCode !== null || child.signalCode !== null) {
-          return false;
-        }
-        try {
-          process.kill(childPid, 0);
-          return true;
-        } catch {
-          return false;
-        }
-      }
-    };
-    const waitForStreamingProcessGroupExit = async (timeoutBudgetMs: number): Promise<boolean> => {
-      const deadlineAt = Date.now() + timeoutBudgetMs;
-      while (Date.now() < deadlineAt) {
-        if (!streamingProcessGroupAlive()) {
-          return true;
-        }
-        await new Promise((resolvePoll) => {
-          setTimeout(resolvePoll, HOST_COMMAND_PROCESS_GROUP_EXIT_POLL_MS);
-        });
-      }
-      return !streamingProcessGroupAlive();
-    };
+    const streamingProcessGroupAlive = (): boolean =>
+      inspectManagedProcessGroup(child, {
+        errorPolicy: "verify-leader",
+        useProcessGroup: detached,
+      }) === "live";
+    const waitForStreamingProcessGroupExit = (timeoutBudgetMs: number): Promise<boolean> =>
+      waitForManagedProcessGroupExit(child, timeoutBudgetMs, {
+        errorPolicy: "verify-leader",
+        useProcessGroup: detached,
+      });
     logStream?.on("error", (error) => {
       logStreamError = error;
       signalStreamingChild("SIGTERM");
diff --git a/scripts/lib/cross-os-release-checks/process.ts b/scripts/lib/cross-os-release-checks/process.ts
index ac3e0ba065e0..f274d1a9e656 100644
--- a/scripts/lib/cross-os-release-checks/process.ts
+++ b/scripts/lib/cross-os-release-checks/process.ts
@@ -16,6 +16,7 @@ import { dirname } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { buildCmdExeCommandLine, resolveWindowsCmdExePath } from "../../windows-cmd-helpers.mjs";
 import { toStringifiedError } from "../error-format.mts";
+import { terminateManagedChild } from "../managed-child-process.mts";
 import { resolveWindowsTaskkillPath } from "../windows-taskkill.mjs";
 import type {
   Cleanup,
@@ -195,15 +196,12 @@ export async function stopGateway(gateway: GatewayHandle | null) {
 }
 
 function signalChildProcessTree(child: ChildProcess, signal: NodeJS.Signals) {
-  if (process.platform !== "win32" && child.pid) {
-    try {
-      process.kill(-child.pid, signal);
-      return;
-    } catch {
-      // The child may have exited before its process group was signaled.
-    }
-  }
-  child.kill(signal);
+  terminateManagedChild(child, signal, {
+    onChildSignalError(error) {
+      throw error;
+    },
+    useWindowsTaskkill: false,
+  });
 }
 
 export function registerActiveChildProcessTree(child: ChildProcess) {
diff --git a/scripts/lib/gateway-bench-child.ts b/scripts/lib/gateway-bench-child.ts
index c531fa86f6ed..7b96aef8006b 100644
--- a/scripts/lib/gateway-bench-child.ts
+++ b/scripts/lib/gateway-bench-child.ts
@@ -1,7 +1,11 @@
 // Gateway Bench Child script supports OpenClaw repository automation.
-import { spawnSync, type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import {
+  inspectManagedProcessGroup,
+  terminateManagedChild,
+  waitForManagedProcessGroupExit,
+} from "./managed-child-process.mts";
 import { sleep as delay } from "./sleep.mjs";
-import { resolveWindowsTaskkillPath } from "./windows-taskkill.mjs";
 
 export { delay };
 
@@ -20,8 +24,6 @@ export type StopChildResult = ChildExit & {
 
 type StopChildOptions = {
   killGraceMs?: number;
-  platform?: NodeJS.Platform;
-  runTaskkill?: typeof spawnSync;
   teardownGraceMs?: number;
 };
 
@@ -31,9 +33,27 @@ export async function stopChild(
 ): Promise<StopChildResult> {
   const teardownGraceMs = options.teardownGraceMs ?? TEARDOWN_GRACE_MS;
   const killGraceMs = options.killGraceMs ?? TEARDOWN_KILL_GRACE_MS;
-  const processTreeOptions = {
-    platform: options.platform ?? process.platform,
-    runTaskkill: options.runTaskkill ?? spawnSync,
+  const processTreeAlive = () =>
+    inspectManagedProcessGroup(child, { errorPolicy: "alive-on-eperm" }) === "live";
+  const signalProcessTree = (signal: NodeJS.Signals): boolean => {
+    let delivered = true;
+    terminateManagedChild(
+      {
+        kill(childSignal) {
+          delivered = child.kill(childSignal);
+          return delivered;
+        },
+        pid: child.pid,
+      },
+      signal,
+      {
+        onChildSignalError(error) {
+          throw error;
+        },
+        taskkillTimeoutMs: null,
+      },
+    );
+    return delivered;
   };
   let observedExit: ChildExit | null = null;
   const directExit = (): ChildExit | null =>
@@ -43,34 +63,30 @@ export async function stopChild(
       : null);
   const currentExit = (): ChildExit | null => {
     const exit = directExit();
-    if (exit == null || isProcessTreeAlive(child, processTreeOptions)) {
+    if (exit == null || processTreeAlive()) {
       return null;
     }
     return exit;
   };
-  const waitForProcessTreeExit = async (ms: number): Promise<boolean> => {
-    const deadlineAt = Date.now() + ms;
-    while (Date.now() < deadlineAt) {
-      if (!isProcessTreeAlive(child, processTreeOptions)) {
-        return true;
-      }
-      await delay(Math.min(EXIT_POLL_MS, deadlineAt - Date.now()));
-    }
-    return !isProcessTreeAlive(child, processTreeOptions);
-  };
+  const waitForProcessTreeExit = (ms: number): Promise<boolean> =>
+    waitForManagedProcessGroupExit(child, ms, {
+      clampPollToDeadline: true,
+      errorPolicy: "alive-on-eperm",
+      pollIntervalMs: EXIT_POLL_MS,
+    });
   const cleanupExitedProcessTree = async (
     exit: ChildExit,
     exitedBeforeTeardown: boolean,
   ): Promise<StopChildResult> => {
-    if (!isProcessTreeAlive(child, processTreeOptions)) {
+    if (!processTreeAlive()) {
       return { ...exit, exitedBeforeTeardown };
     }
-    const sentTeardownSignal = killProcessTree(child, "SIGTERM", processTreeOptions);
+    const sentTeardownSignal = signalProcessTree("SIGTERM");
     if (sentTeardownSignal) {
       await waitForProcessTreeExit(teardownGraceMs);
     }
-    if (sentTeardownSignal && isProcessTreeAlive(child, processTreeOptions)) {
-      killProcessTree(child, "SIGKILL", processTreeOptions);
+    if (sentTeardownSignal && processTreeAlive()) {
+      signalProcessTree("SIGKILL");
       await waitForProcessTreeExit(killGraceMs);
     }
     if (!sentTeardownSignal) {
@@ -115,7 +131,7 @@ export async function stopChild(
     return await cleanupExitedProcessTree(queuedExit, true);
   }
 
-  const sentTeardownSignal = killProcessTree(child, "SIGTERM", processTreeOptions);
+  const sentTeardownSignal = signalProcessTree("SIGTERM");
   const gracefulExit = await waitForExit(teardownGraceMs);
   if (gracefulExit != null) {
     return { ...gracefulExit, exitedBeforeTeardown: !sentTeardownSignal };
@@ -130,7 +146,7 @@ export async function stopChild(
     return { exitCode: null, exitedBeforeTeardown: true, signal: null };
   }
 
-  killProcessTree(child, "SIGKILL", processTreeOptions);
+  signalProcessTree("SIGKILL");
   const killedExit = await waitForExit(killGraceMs);
   const finalExit = killedExit ?? currentExit();
   if (finalExit != null) {
@@ -147,56 +163,3 @@ function releaseUnsettledChild(child: ChildProcessWithoutNullStreams): void {
   child.stderr.destroy();
   child.unref();
 }
-
-function isProcessTreeAlive(
-  child: ChildProcessWithoutNullStreams,
-  { platform = process.platform }: Pick<StopChildOptions, "platform"> = {},
-): boolean {
-  if (platform === "win32" || child.pid === undefined) {
-    return false;
-  }
-  try {
-    process.kill(-child.pid, 0);
-    return true;
-  } catch (error) {
-    return isProcessStillExistsError(error);
-  }
-}
-
-function isProcessStillExistsError(error: unknown): boolean {
-  const code = (error as { code?: unknown }).code;
-  return code === "EPERM";
-}
-
-function killProcessTree(
-  child: ChildProcessWithoutNullStreams,
-  signal: NodeJS.Signals,
-  { platform = process.platform, runTaskkill = spawnSync }: StopChildOptions = {},
-): boolean {
-  if (platform !== "win32" && child.pid !== undefined) {
-    try {
-      process.kill(-child.pid, signal);
-      return true;
-    } catch {
-      // Fall back to the direct child below.
-    }
-  }
-  if (platform === "win32" && child.pid !== undefined) {
-    const args = ["/PID", String(child.pid), "/T"];
-    if (signal === "SIGKILL") {
-      args.push("/F");
-    }
-    const taskkillPath = resolveWindowsTaskkillPath();
-    const result = runTaskkill(taskkillPath, args, { stdio: "ignore" });
-    if (!result?.error && result?.status === 0) {
-      return true;
-    }
-    if (signal !== "SIGKILL") {
-      const forceResult = runTaskkill(taskkillPath, [...args, "/F"], { stdio: "ignore" });
-      if (!forceResult?.error && forceResult?.status === 0) {
-        return true;
-      }
-    }
-  }
-  return child.kill(signal);
-}
diff --git a/scripts/lib/managed-child-process.mts b/scripts/lib/managed-child-process.mts
index aac61e0031b4..2bddb5dbb934 100644
--- a/scripts/lib/managed-child-process.mts
+++ b/scripts/lib/managed-child-process.mts
@@ -12,11 +12,33 @@ const PROCESS_GROUP_POLL_MS = 25;
 const TASKKILL_TIMEOUT_MS = 10_000;
 type ProcessTreeState = "indeterminate" | "live" | "signaled" | "terminated";
 type ManagedChildTermination = { processTreeState: Exclude<ProcessTreeState, "live"> };
+type ManagedProcessGroupErrorPolicy = "alive-on-eperm" | "indeterminate" | "verify-leader";
+type ManagedProcessGroupChild = {
+  exitCode?: number | null;
+  pid?: number;
+  signalCode?: string | null;
+};
+type ManagedProcessGroupOptions = {
+  errorPolicy: ManagedProcessGroupErrorPolicy;
+  inspectLeaderWhenNoGroup?: boolean;
+  platform?: NodeJS.Platform;
+  useProcessGroup?: boolean;
+};
 type TaskkillRunner = (
   command: string,
   args: string[],
   options: { killSignal?: NodeJS.Signals; stdio?: StdioOptions; timeout?: number },
 ) => { error?: Error; status: number | null } | undefined;
+type ManagedChildTerminationOptions = {
+  onChildSignalError?: (error: unknown) => void;
+  onProcessGroupSignalError?: (error: unknown) => void;
+  platform?: NodeJS.Platform;
+  processGroupFallback?: "always" | "never" | "nonmissing";
+  runTaskkill?: TaskkillRunner;
+  taskkillTimeoutMs?: number | null;
+  useProcessGroup?: boolean;
+  useWindowsTaskkill?: boolean;
+};
 
 type ManagedCommandOptions = {
   bin: string;
@@ -60,28 +82,22 @@ export function signalExitCode(signal: NodeJS.Signals) {
 /**
  * @param {import("node:child_process").ChildProcess} child
  * @param {NodeJS.Signals} [signal]
- * @param {{
- *   onProcessGroupSignalError?: (error: unknown) => void;
- *   platform?: NodeJS.Platform;
- *   runTaskkill?: typeof spawnSync;
- *   useProcessGroup?: boolean;
- * }} [options]
+ * @param {ManagedChildTerminationOptions} [options]
  * @returns {{ processTreeState: "indeterminate" | "signaled" | "terminated" } | undefined}
  */
 export function terminateManagedChild(
-  child: { kill(signal?: NodeJS.Signals): unknown; pid?: number },
+  child: { kill(signal: NodeJS.Signals): unknown; pid?: number },
   signal: NodeJS.Signals = "SIGTERM",
   {
+    onChildSignalError,
     onProcessGroupSignalError,
     platform = process.platform,
+    processGroupFallback = "always",
     runTaskkill = spawnSync,
+    taskkillTimeoutMs = TASKKILL_TIMEOUT_MS,
     useProcessGroup = platform !== "win32",
-  }: {
-    onProcessGroupSignalError?: (error: unknown) => void;
-    platform?: NodeJS.Platform;
-    runTaskkill?: TaskkillRunner;
-    useProcessGroup?: boolean;
-  } = {},
+    useWindowsTaskkill = true,
+  }: ManagedChildTerminationOptions = {},
 ): ManagedChildTermination | undefined {
   if (!child.pid) {
     try {
@@ -89,7 +105,8 @@ export function terminateManagedChild(
       if (platform !== "win32") {
         return { processTreeState: delivered === false ? "terminated" : "signaled" };
       }
-    } catch {
+    } catch (error) {
+      onChildSignalError?.(error);
       // A child that never acquired a PID may already have failed to spawn.
     }
     return platform === "win32" ? { processTreeState: "indeterminate" } : undefined;
@@ -101,49 +118,130 @@ export function terminateManagedChild(
       return { processTreeState: "signaled" };
     }
   } catch (error) {
-    if (!isMissingProcessError(error)) {
+    const processGroupIsMissing = isMissingProcessError(error);
+    if (!processGroupIsMissing) {
       onProcessGroupSignalError?.(error);
     }
+    if (
+      processGroupFallback === "never" ||
+      (processGroupFallback === "nonmissing" && processGroupIsMissing)
+    ) {
+      return processGroupIsMissing ? { processTreeState: "terminated" } : undefined;
+    }
   }
 
-  if (platform !== "win32") {
+  if (platform !== "win32" || !useWindowsTaskkill) {
     try {
       const delivered = child.kill(signal);
       return { processTreeState: delivered === false ? "terminated" : "signaled" };
     } catch (error) {
+      onChildSignalError?.(error);
       return isMissingProcessError(error) ? { processTreeState: "terminated" } : undefined;
     }
   }
 
-  if (platform === "win32") {
-    const taskkillPath = resolveWindowsTaskkillPath();
-    const args = ["/PID", String(child.pid), "/T"];
-    if (signal === "SIGKILL") {
-      args.push("/F");
-    }
-    const taskkillOptions = {
-      killSignal: "SIGKILL",
-      stdio: "ignore",
-      timeout: TASKKILL_TIMEOUT_MS,
-    } satisfies Parameters<TaskkillRunner>[2];
-    const result = runTaskkill(taskkillPath, args, taskkillOptions);
-    if (!result?.error && result?.status === 0) {
+  const taskkillPath = resolveWindowsTaskkillPath();
+  const args = ["/PID", String(child.pid), "/T"];
+  if (signal === "SIGKILL") {
+    args.push("/F");
+  }
+  const taskkillOptions: Parameters<TaskkillRunner>[2] =
+    taskkillTimeoutMs === null
+      ? { stdio: "ignore" }
+      : { killSignal: "SIGKILL", stdio: "ignore", timeout: taskkillTimeoutMs };
+  const result = runTaskkill(taskkillPath, args, taskkillOptions);
+  if (!result?.error && result?.status === 0) {
+    return { processTreeState: "terminated" };
+  }
+  if (signal !== "SIGKILL") {
+    const forceResult = runTaskkill(taskkillPath, [...args, "/F"], taskkillOptions);
+    if (!forceResult?.error && forceResult?.status === 0) {
       return { processTreeState: "terminated" };
     }
-    if (signal !== "SIGKILL") {
-      const forceResult = runTaskkill(taskkillPath, [...args, "/F"], taskkillOptions);
-      if (!forceResult?.error && forceResult?.status === 0) {
-        return { processTreeState: "terminated" };
-      }
+  }
+  try {
+    child.kill(signal);
+  } catch (error) {
+    onChildSignalError?.(error);
+    // The leader may already be gone, but failed taskkill leaves descendants unverified.
+  }
+  return { processTreeState: "indeterminate" };
+}
+
+export function inspectManagedProcessGroup(
+  child: ManagedProcessGroupChild,
+  {
+    errorPolicy,
+    inspectLeaderWhenNoGroup = false,
+    platform = process.platform,
+    useProcessGroup = platform !== "win32",
+  }: ManagedProcessGroupOptions,
+): "dead" | "indeterminate" | "live" {
+  if (!useProcessGroup) {
+    return inspectLeaderWhenNoGroup &&
+      child.pid &&
+      child.exitCode === null &&
+      child.signalCode === null
+      ? "live"
+      : "dead";
+  }
+  const { pid } = child;
+  if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 1 || pid > 0x7fffffff) {
+    return "indeterminate";
+  }
+  try {
+    process.kill(-pid, 0);
+    return "live";
+  } catch (error) {
+    if (isMissingProcessError(error)) {
+      return "dead";
+    }
+    if (errorPolicy === "indeterminate") {
+      return "indeterminate";
+    }
+    if (!hasProcessErrorCode(error, "EPERM")) {
+      return "dead";
+    }
+    if (errorPolicy === "alive-on-eperm") {
+      return "live";
+    }
+    if (child.exitCode != null || child.signalCode != null) {
+      return "dead";
     }
     try {
-      child.kill(signal);
+      process.kill(pid, 0);
+      return "live";
     } catch {
-      // The leader may already be gone, but failed taskkill leaves descendants unverified.
+      return "dead";
     }
-    return { processTreeState: "indeterminate" };
   }
-  return undefined;
+}
+
+export async function waitForManagedProcessGroupExit(
+  child: ManagedProcessGroupChild,
+  timeoutMs: number,
+  {
+    clampPollToDeadline = false,
+    pollIntervalMs = PROCESS_GROUP_POLL_MS,
+    ...groupOptions
+  }: ManagedProcessGroupOptions & {
+    clampPollToDeadline?: boolean;
+    pollIntervalMs?: number;
+  },
+): Promise<boolean> {
+  const deadlineAt = Date.now() + timeoutMs;
+  while (Date.now() < deadlineAt) {
+    if (inspectManagedProcessGroup(child, groupOptions) !== "live") {
+      return true;
+    }
+    const waitMs = clampPollToDeadline
+      ? Math.min(pollIntervalMs, deadlineAt - Date.now())
+      : pollIntervalMs;
+    await new Promise((resolve) => {
+      setTimeout(resolve, waitMs);
+    });
+  }
+  return inspectManagedProcessGroup(child, groupOptions) !== "live";
 }
 
 /**
@@ -318,18 +416,6 @@ function createManagedCommandSetupCleanupError(error: unknown, cleanupError: unk
   );
 }
 
-function processGroupStatus(pid: number | undefined): "dead" | "indeterminate" | "live" {
-  if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 1 || pid > 0x7fffffff) {
-    return "indeterminate";
-  }
-  try {
-    process.kill(-pid, 0);
-    return "live";
-  } catch (error) {
-    return isMissingProcessError(error) ? "dead" : "indeterminate";
-  }
-}
-
 async function ensureManagedProcessTreeExit(
   child: ChildProcess,
   platform: NodeJS.Platform,
@@ -349,11 +435,14 @@ async function ensureManagedProcessTreeExit(
     }
     return;
   }
-  const initialStatus = processGroupStatus(child.pid);
+  const initialStatus = inspectManagedProcessGroup(child, {
+    errorPolicy: "indeterminate",
+    platform,
+  });
   if (initialStatus === "dead") {
     return;
   }
-  let status: ReturnType<typeof processGroupStatus> = initialStatus;
+  let status: ReturnType<typeof inspectManagedProcessGroup> = initialStatus;
   // A missing group at signal time supersedes the earlier racy liveness probe.
   const termination = terminateIfLive
     ? terminateManagedChild(child, "SIGKILL", { platform })
@@ -363,7 +452,7 @@ async function ensureManagedProcessTreeExit(
     await new Promise((resolve) => {
       setTimeout(resolve, PROCESS_GROUP_POLL_MS);
     });
-    status = processGroupStatus(child.pid);
+    status = inspectManagedProcessGroup(child, { errorPolicy: "indeterminate", platform });
     if (status === "dead") {
       if (terminateIfLive && termination?.processTreeState !== "terminated") {
         throw createManagedCommandCleanupError(
@@ -568,5 +657,9 @@ function signalNumberFor(signal: NodeJS.Signals) {
 }
 
 function isMissingProcessError(error: unknown) {
-  return Boolean(error && typeof error === "object" && "code" in error && error.code === "ESRCH");
+  return hasProcessErrorCode(error, "ESRCH");
+}
+
+function hasProcessErrorCode(error: unknown, code: string) {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
 }
diff --git a/scripts/run-additional-boundary-checks.mts b/scripts/run-additional-boundary-checks.mts
index 46172397f458..46bee1ed5c30 100644
--- a/scripts/run-additional-boundary-checks.mts
+++ b/scripts/run-additional-boundary-checks.mts
@@ -10,12 +10,16 @@ import {
   resolveTimerTimeoutMs,
 } from "../packages/normalization-core/src/number-coercion.ts";
 import { isDirectRunUrl } from "./lib/direct-run.mjs";
+import {
+  inspectManagedProcessGroup,
+  terminateManagedChild,
+  waitForManagedProcessGroupExit,
+} from "./lib/managed-child-process.mts";
 
 const DEFAULT_CHECK_TIMEOUT_MS = 10 * 60 * 1000;
 const DEFAULT_OUTPUT_MAX_BYTES = 512 * 1024;
 // Boundary checks are disposable subprocesses; bound descendant cleanup after timeout.
 const TIMEOUT_KILL_GRACE_MS = 250;
-const PROCESS_GROUP_EXIT_POLL_MS = 25;
 const POST_FORCE_KILL_WAIT_MS = 250;
 
 type ProcessSignal = `SIG${string}`;
@@ -294,38 +298,20 @@ export function createBoundedOutputBuffer(maxBytes = DEFAULT_OUTPUT_MAX_BYTES) {
 }
 
 function terminateChild(child: ChildProcess, signal: ProcessSignal) {
-  if (process.platform !== "win32" && child.pid) {
-    try {
-      process.kill(-child.pid, signal as NodeJS.Signals);
-      return;
-    } catch {}
-  }
-  child.kill(signal as NodeJS.Signals);
+  terminateManagedChild(child, signal as NodeJS.Signals, {
+    onChildSignalError(error) {
+      throw error;
+    },
+    useWindowsTaskkill: false,
+  });
 }
 
 function processGroupAlive(child: ChildProcess) {
-  if (process.platform === "win32" || !child.pid) {
-    return false;
-  }
-  try {
-    process.kill(-child.pid, 0);
-    return true;
-  } catch (error) {
-    return typeof error === "object" && error !== null && "code" in error && error.code === "EPERM";
-  }
+  return inspectManagedProcessGroup(child, { errorPolicy: "alive-on-eperm" }) === "live";
 }
 
-async function waitForProcessGroupExit(child: ChildProcess, timeoutMs: number) {
-  const deadlineAt = Date.now() + timeoutMs;
-  while (Date.now() < deadlineAt) {
-    if (!processGroupAlive(child)) {
-      return true;
-    }
-    await new Promise((resolvePoll) => {
-      setTimeout(resolvePoll, PROCESS_GROUP_EXIT_POLL_MS);
-    });
-  }
-  return !processGroupAlive(child);
+function waitForProcessGroupExit(child: ChildProcess, timeoutMs: number) {
+  return waitForManagedProcessGroupExit(child, timeoutMs, { errorPolicy: "alive-on-eperm" });
 }
 
 async function finishTerminatedProcessTree(
diff --git a/scripts/run-oxlint-shards.mts b/scripts/run-oxlint-shards.mts
index c5b619ba0201..3d9f25316bd6 100644
--- a/scripts/run-oxlint-shards.mts
+++ b/scripts/run-oxlint-shards.mts
@@ -8,6 +8,11 @@ import {
   resolveLocalCheckEnv,
   resolveRepoToolBinPath,
 } from "./lib/local-check-runtime.mts";
+import {
+  inspectManagedProcessGroup,
+  terminateManagedChild,
+  waitForManagedProcessGroupExit,
+} from "./lib/managed-child-process.mts";
 import { shouldPrepareExtensionPackageBoundaryArtifacts } from "./run-oxlint.mts";
 
 const DEFAULT_WINDOWS_EXTENSION_CHUNK_SIZE = 8;
@@ -15,7 +20,6 @@ const DEFAULT_SHARD_HEARTBEAT_MS = 30_000;
 const DEFAULT_SHARD_TIMEOUT_MS = 15 * 60_000;
 const DEFAULT_SHARD_KILL_GRACE_MS = 5_000;
 const POST_FORCE_KILL_WAIT_MS = 1_000;
-const PROCESS_GROUP_EXIT_POLL_MS = 25;
 const DEFAULT_SPLIT_CORE_SHARD_CONCURRENCY = 4;
 const FAST_LOCAL_CHECK_MIN_CPUS = 12;
 const FAST_LOCAL_CHECK_MIN_MEMORY_BYTES = 48 * 1024 ** 3;
@@ -46,13 +50,10 @@ type RunnerOptions = {
 };
 type ShardRunnerOptions = RunnerOptions & { shard: OxlintShard };
 type ShardBatchOptions = RunnerOptions & { concurrency: number; entries: OxlintShard[] };
-type ChildProcessGroupOptions = { child: ChildProcess; useProcessGroup: boolean };
-type ActiveShardChild = ChildProcessGroupOptions & { killGraceMs: number };
-type SignalOptions = ChildProcessGroupOptions & { signal: NodeJS.Signals };
-type WaitOptions = ChildProcessGroupOptions & { timeoutMs: number };
+type ActiveShardChild = { child: ChildProcess; killGraceMs: number };
 
 const ACTIVE_SHARD_CHILDREN = new Set<ActiveShardChild>();
-let parentTerminationSignal: NodeJS.Signals | null = null;
+let parentTerminationSignal: (typeof PARENT_TERMINATION_SIGNALS)[number] | null = null;
 let parentTerminationForceKill: ReturnType<typeof setTimeout> | null = null;
 let parentSignalForwardingInstalled = false;
 
@@ -508,16 +509,15 @@ export async function runShard({ env, extraArgs, runner, shard }: ShardRunnerOpt
   const heartbeatMs = resolveShardHeartbeatMs(env);
   const timeoutMs = resolveShardTimeoutMs(env);
   const killGraceMs = resolveShardKillGraceMs(env);
-  const useProcessGroup = process.platform !== "win32";
   const child = spawn(process.execPath, [runner, ...shard.args, ...extraArgs], {
     stdio: "inherit",
-    detached: useProcessGroup,
+    detached: process.platform !== "win32",
     env: {
       ...env,
       OPENCLAW_OXLINT_SKIP_PREPARE: "1",
     },
   });
-  const unregisterShardChild = registerShardChild({ child, killGraceMs, useProcessGroup });
+  const unregisterShardChild = registerShardChild({ child, killGraceMs });
 
   return await new Promise<number>((resolve) => {
     let finished = false;
@@ -540,16 +540,16 @@ export async function runShard({ env, extraArgs, runner, shard }: ShardRunnerOpt
             console.error(
               `[oxlint:${shard.name}] timed out after ${elapsedSeconds}s; terminating shard`,
             );
-            signalChildProcess({ child, signal: "SIGTERM", useProcessGroup });
+            signalChildProcess(child, "SIGTERM");
             if (killGraceMs > 0) {
               forceKillAt = Date.now() + killGraceMs;
               forceKill = setTimeout(() => {
                 console.error(`[oxlint:${shard.name}] did not exit cleanly; killing shard`);
-                signalChildProcess({ child, signal: "SIGKILL", useProcessGroup });
+                signalChildProcess(child, "SIGKILL");
               }, killGraceMs);
               forceKill.unref();
             } else {
-              signalChildProcess({ child, signal: "SIGKILL", useProcessGroup });
+              signalChildProcess(child, "SIGKILL");
             }
           }, timeoutMs)
         : null;
@@ -577,20 +577,12 @@ export async function runShard({ env, extraArgs, runner, shard }: ShardRunnerOpt
       const graceRemainingMs =
         forceKillAt === null ? killGraceMs : Math.max(0, forceKillAt - Date.now());
       if (graceRemainingMs > 0) {
-        await waitForChildProcessGroupExit({
-          child,
-          timeoutMs: graceRemainingMs,
-          useProcessGroup,
-        });
+        await waitForChildProcessGroupExit(child, graceRemainingMs);
       }
-      if (isChildProcessGroupAlive({ child, useProcessGroup })) {
-        signalChildProcess({ child, signal: "SIGKILL", useProcessGroup });
+      if (isChildProcessGroupAlive(child)) {
+        signalChildProcess(child, "SIGKILL");
       }
-      await waitForChildProcessGroupExit({
-        child,
-        timeoutMs: POST_FORCE_KILL_WAIT_MS,
-        useProcessGroup,
-      });
+      await waitForChildProcessGroupExit(child, POST_FORCE_KILL_WAIT_MS);
       finish(status);
     };
     child.once("error", (error) => {
@@ -603,10 +595,7 @@ export async function runShard({ env, extraArgs, runner, shard }: ShardRunnerOpt
         : timedOut
           ? 124
           : (status ?? 1);
-      if (
-        (timedOut || parentTerminationSignal) &&
-        isChildProcessGroupAlive({ child, useProcessGroup })
-      ) {
+      if ((timedOut || parentTerminationSignal) && isChildProcessGroupAlive(child)) {
         void finishAfterForcedTeardown(exitStatus);
         return;
       }
@@ -699,47 +688,30 @@ function parsePositiveEnvInt(rawValue: string, key: string) {
   return parsedValue;
 }
 
-function signalChildProcess({ child, signal, useProcessGroup }: SignalOptions) {
+function signalChildProcess(child: ChildProcess, signal: NodeJS.Signals) {
   if (!child.pid) {
     return;
   }
 
-  try {
-    if (useProcessGroup) {
-      process.kill(-child.pid, signal);
-    } else {
-      child.kill(signal);
-    }
-  } catch (error) {
+  const reportSignalError = (error: unknown) => {
     if (!isNodeErrorCode(error, "ESRCH")) {
       console.error(error);
     }
-  }
+  };
+  terminateManagedChild(child, signal, {
+    onChildSignalError: reportSignalError,
+    onProcessGroupSignalError: reportSignalError,
+    processGroupFallback: "never",
+    useWindowsTaskkill: false,
+  });
 }
 
-function isChildProcessGroupAlive({ child, useProcessGroup }: ChildProcessGroupOptions) {
-  if (!useProcessGroup || !child.pid) {
-    return false;
-  }
-  try {
-    process.kill(-child.pid, 0);
-    return true;
-  } catch (error) {
-    return isNodeErrorCode(error, "EPERM");
-  }
+function isChildProcessGroupAlive(child: ChildProcess) {
+  return inspectManagedProcessGroup(child, { errorPolicy: "alive-on-eperm" }) === "live";
 }
 
-async function waitForChildProcessGroupExit({ child, timeoutMs, useProcessGroup }: WaitOptions) {
-  const deadlineAt = Date.now() + timeoutMs;
-  while (Date.now() < deadlineAt) {
-    if (!isChildProcessGroupAlive({ child, useProcessGroup })) {
-      return true;
-    }
-    await new Promise((resolvePoll) => {
-      setTimeout(resolvePoll, PROCESS_GROUP_EXIT_POLL_MS);
-    });
-  }
-  return !isChildProcessGroupAlive({ child, useProcessGroup });
+function waitForChildProcessGroupExit(child: ChildProcess, timeoutMs: number) {
+  return waitForManagedProcessGroupExit(child, timeoutMs, { errorPolicy: "alive-on-eperm" });
 }
 
 function registerShardChild(entry: ActiveShardChild) {
@@ -781,7 +753,7 @@ function isParentTerminationRequested() {
 
 function signalActiveShardChildren(signal: NodeJS.Signals) {
   for (const entry of ACTIVE_SHARD_CHILDREN) {
-    signalChildProcess({ ...entry, signal });
+    signalChildProcess(entry.child, signal);
   }
 }
 
diff --git a/scripts/test-docker-all.mts b/scripts/test-docker-all.mts
index 00d19d194391..0349b101f591 100644
--- a/scripts/test-docker-all.mts
+++ b/scripts/test-docker-all.mts
@@ -31,6 +31,11 @@ import {
   resolveDockerE2ePlan,
 } from "./lib/docker-e2e-plan.mts";
 import type { DockerE2eLane } from "./lib/docker-e2e-scenarios.mts";
+import {
+  inspectManagedProcessGroup,
+  terminateManagedChild,
+  waitForManagedProcessGroupExit,
+} from "./lib/managed-child-process.mts";
 import { sleep } from "./lib/sleep.mjs";
 import {
   createPrepublishPluginRegistryArtifact,
@@ -54,7 +59,6 @@ export const SHELL_CAPTURE_MAX_CHARS = 1024 * 1024;
 export const LOG_TAIL_MAX_BYTES = 1024 * 1024;
 const SHELL_TIMEOUT_KILL_GRACE_MS = 10_000;
 const SHELL_POST_FORCE_KILL_WAIT_MS = 1_000;
-const SHELL_PROCESS_GROUP_EXIT_POLL_MS = 25;
 const MAX_TIMER_TIMEOUT_MS = 2_147_000_000;
 const DEFAULT_TIMINGS_FILE = path.join(ROOT_DIR, ".artifacts/docker-tests/lane-timings.json");
 const DEFAULT_GITHUB_WORKFLOW = "openclaw-live-and-e2e-checks-reusable.yml";
@@ -82,10 +86,10 @@ type SchedulerLane = Pick<DockerE2eLane, "name"> &
 type TimingStore = Awaited<ReturnType<typeof loadTimingStore>>;
 
 type ShellCommandResult = Omit<ReturnType<typeof shellCommandSkippedForShutdown>, "signal"> & {
-  signal: NodeJS.Signals | null;
+  signal: ChildProcess["signalCode"];
 };
 type ShellCaptureResult = Omit<ReturnType<typeof shellCaptureSkippedForShutdown>, "signal"> & {
-  signal: NodeJS.Signals | null;
+  signal: ChildProcess["signalCode"];
 };
 
 type ShellCommandOptions = {
@@ -1625,28 +1629,11 @@ function shellCaptureSkippedForShutdown(label: string, signal: ShutdownSignal |
 }
 
 function shellProcessGroupAlive(child: ChildProcess) {
-  if (process.platform === "win32" || !child.pid) {
-    return false;
-  }
-  try {
-    process.kill(-child.pid, 0);
-    return true;
-  } catch (error) {
-    return error instanceof Error && "code" in error && error.code === "EPERM";
-  }
+  return inspectManagedProcessGroup(child, { errorPolicy: "alive-on-eperm" }) === "live";
 }
 
-async function waitForShellProcessGroupExit(child: ChildProcess, timeoutMs: number) {
-  const deadlineAt = Date.now() + timeoutMs;
-  while (Date.now() < deadlineAt) {
-    if (!shellProcessGroupAlive(child)) {
-      return true;
-    }
-    await new Promise((resolvePoll) => {
-      setTimeout(resolvePoll, SHELL_PROCESS_GROUP_EXIT_POLL_MS);
-    });
-  }
-  return !shellProcessGroupAlive(child);
+function waitForShellProcessGroupExit(child: ChildProcess, timeoutMs: number) {
+  return waitForManagedProcessGroupExit(child, timeoutMs, { errorPolicy: "alive-on-eperm" });
 }
 
 async function finishTimedOutShellProcessTree(
@@ -1669,15 +1656,12 @@ async function finishTimedOutShellProcessTree(
 }
 
 function terminateChild(child: ChildProcess, signal: ShutdownSignal) {
-  if (process.platform !== "win32" && child.pid) {
-    try {
-      process.kill(-child.pid, signal);
-      return;
-    } catch {
-      // Fall back to killing the direct child below.
-    }
-  }
-  child.kill(signal);
+  terminateManagedChild(child, signal, {
+    onChildSignalError(error) {
+      throw error;
+    },
+    useWindowsTaskkill: false,
+  });
 }
 
 function terminateActiveChildren(signal: ShutdownSignal) {
diff --git a/scripts/test-group-report.mts b/scripts/test-group-report.mts
index 337c93f2bf08..56d0d7f0bdde 100644
--- a/scripts/test-group-report.mts
+++ b/scripts/test-group-report.mts
@@ -1,5 +1,5 @@
 // Builds grouped Vitest duration reports or compares two grouped reports.
-import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import { spawn } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -7,6 +7,11 @@ import { pathToFileURL } from "node:url";
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import pMap from "p-map";
 import { coerceErrorMessage } from "./lib/error-format.mts";
+import {
+  inspectManagedProcessGroup,
+  terminateManagedChild,
+  waitForManagedProcessGroupExit,
+} from "./lib/managed-child-process.mts";
 import { parsePositiveInt } from "./lib/numeric-options.mjs";
 import {
   buildGroupedTestComparison,
@@ -17,7 +22,6 @@ import {
   renderGroupedTestReport,
 } from "./lib/test-group-report.mts";
 import { formatMs } from "./lib/vitest-report-cli-utils.mts";
-import { resolveWindowsTaskkillPath } from "./lib/windows-taskkill.mjs";
 import { resolveVitestNodeArgs } from "./run-vitest.mts";
 import {
   applyParallelVitestCachePaths,
@@ -31,7 +35,6 @@ const DEFAULT_TIMEOUT_KILL_GRACE_MS = 10_000;
 const DEFAULT_SPAWN_LOG_MAX_BYTES = 1024 * 1024 * 256;
 const DEFAULT_SPAWN_OUTPUT_MAX_BYTES = 1024 * 1024 * 64;
 const DEFAULT_SPAWN_OUTPUT_TAIL_BYTES = 1024 * 256;
-const PROCESS_GROUP_EXIT_POLL_MS = 25;
 
 type ProcessSignal = `SIG${string}`;
 type TimerHandle = ReturnType<typeof setTimeout>;
@@ -97,12 +100,6 @@ type RunVitestParams = TestGroupRunSpec &
     reportPath: string;
   };
 
-type TaskkillRunner = (
-  command: string,
-  args: string[],
-  options: { stdio: "ignore" },
-) => { error?: Error; status: number | null };
-
 function usage() {
   return [
     "Usage: node --import tsx scripts/test-group-report.mts [options] [-- <vitest args>]",
@@ -335,57 +332,6 @@ function parseMaxRssBytes(output: string) {
   return null;
 }
 
-function hasErrorCode(error: unknown, code: string) {
-  return isRecord(error) && error.code === code;
-}
-
-export function signalTestGroupReportChild(
-  child: Pick<ChildProcess, "kill" | "pid">,
-  signal: ProcessSignal,
-  {
-    appendDiagnostic = () => {},
-    platform = process.platform,
-    runTaskkill = spawnSync,
-    useProcessGroup = platform !== "win32",
-  }: {
-    appendDiagnostic?: (message: string) => void;
-    platform?: typeof process.platform;
-    runTaskkill?: TaskkillRunner;
-    useProcessGroup?: boolean;
-  } = {},
-) {
-  if (useProcessGroup && typeof child.pid === "number") {
-    try {
-      process.kill(-child.pid, signal as NodeJS.Signals);
-      return;
-    } catch (error) {
-      if (error && !hasErrorCode(error, "ESRCH")) {
-        appendDiagnostic(
-          `[test-group-report] failed to send ${signal} to process group: ${coerceErrorMessage(error)}\n`,
-        );
-      }
-    }
-  }
-  if (platform === "win32" && typeof child.pid === "number") {
-    const args = ["/PID", String(child.pid), "/T"];
-    if (signal === "SIGKILL") {
-      args.push("/F");
-    }
-    const taskkillPath = resolveWindowsTaskkillPath();
-    const result = runTaskkill(taskkillPath, args, { stdio: "ignore" });
-    if (!result?.error && result?.status === 0) {
-      return;
-    }
-    if (signal !== "SIGKILL") {
-      const forceResult = runTaskkill(taskkillPath, [...args, "/F"], { stdio: "ignore" });
-      if (!forceResult?.error && forceResult?.status === 0) {
-        return;
-      }
-    }
-  }
-  child.kill(signal as NodeJS.Signals);
-}
-
 /**
  * Runs a command, captures text output, and terminates timed-out process groups.
  */
@@ -422,7 +368,17 @@ export function spawnText(command: string, args: readonly string[], options: Spa
     let childClosedResult: SpawnTextResult | null = null;
     let waitingForKillGrace = false;
     const signalChild = (signal: ProcessSignal) =>
-      signalTestGroupReportChild(child, signal, { appendDiagnostic, useProcessGroup });
+      terminateManagedChild(child, signal as NodeJS.Signals, {
+        onChildSignalError(error) {
+          throw error;
+        },
+        onProcessGroupSignalError(error) {
+          appendDiagnostic(
+            `[test-group-report] failed to send ${signal} to process group: ${coerceErrorMessage(error)}\n`,
+          );
+        },
+        taskkillTimeoutMs: null,
+      });
     const parentSignalHandlers: { signal: ProcessSignal; handler: () => void }[] = [];
     const cleanupParentSignalHandlers = () => {
       for (const { signal, handler } of parentSignalHandlers) {
@@ -448,34 +404,15 @@ export function spawnText(command: string, args: readonly string[], options: Spa
       relayParentSignal("SIGINT");
       relayParentSignal("SIGTERM");
     }
-    const processGroupIsAlive = () => {
-      if (!useProcessGroup || typeof child.pid !== "number") {
-        return false;
-      }
-      try {
-        process.kill(-child.pid, 0);
-        return true;
-      } catch (error) {
-        return Boolean(error && hasErrorCode(error, "EPERM"));
-      }
-    };
-    const waitForProcessGroupExit = async (timeoutMsToWait: number) => {
-      const deadlineAt = Date.now() + timeoutMsToWait;
-      while (Date.now() < deadlineAt) {
-        if (!processGroupIsAlive()) {
-          return true;
-        }
-        await new Promise((resolvePoll) => {
-          setTimeout(resolvePoll, PROCESS_GROUP_EXIT_POLL_MS);
-        });
-      }
-      return !processGroupIsAlive();
-    };
+    const processGroupIsAlive = () =>
+      inspectManagedProcessGroup(child, { errorPolicy: "alive-on-eperm" }) === "live";
     const finishAfterProcessGroupCleanup = async (result: SpawnTextResult) => {
       const graceRemainingMs =
         killGraceDeadline === null ? killGraceMs : Math.max(0, killGraceDeadline - Date.now());
       if (graceRemainingMs > 0) {
-        await waitForProcessGroupExit(graceRemainingMs);
+        await waitForManagedProcessGroupExit(child, graceRemainingMs, {
+          errorPolicy: "alive-on-eperm",
+        });
       }
       if (settled) {
         return;
diff --git a/scripts/tsdown-build.mts b/scripts/tsdown-build.mts
index cdba28dd34f8..f359f4b51e08 100644
--- a/scripts/tsdown-build.mts
+++ b/scripts/tsdown-build.mts
@@ -13,7 +13,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { BUNDLED_PLUGIN_PATH_PREFIX } from "./lib/bundled-plugin-paths.mjs";
-import { terminateManagedChild } from "./lib/managed-child-process.mts";
+import {
+  inspectManagedProcessGroup,
+  terminateManagedChild,
+  waitForManagedProcessGroupExit,
+} from "./lib/managed-child-process.mts";
 import { parsePositiveInt } from "./lib/numeric-options.mjs";
 import { assertRealOutputRoot } from "./lib/output-root-guard.mjs";
 import {
@@ -51,7 +55,6 @@ const PROC_MEMINFO_PATH = "/proc/meminfo";
 const tsdownStdio = () => ["ignore", "pipe", "pipe"] satisfies ["ignore", "pipe", "pipe"];
 // Build descendants get a short cleanup window; a timed-out build must not hold CI for seconds.
 const TERMINATION_GRACE_MS = 250;
-const PROCESS_GROUP_EXIT_POLL_MS = 25;
 const POST_FORCE_KILL_WAIT_MS = 250;
 const ROOT_TSDOWN_OUTPUT_ROOTS = ["dist", "dist-runtime"];
 const PRESERVED_TSDOWN_OUTPUT_FILES = ["dist/cli-startup-metadata.json"];
@@ -899,35 +902,18 @@ export async function runTsdownBuildInvocation(
     relayParentSignal("SIGHUP");
   }
 
-  function processTreeAlive() {
-    if (!child.pid) {
-      return false;
-    }
-    if (!useProcessGroup) {
-      return child.exitCode === null && child.signalCode === null;
-    }
-    try {
-      process.kill(-child.pid, 0);
-      return true;
-    } catch (error) {
-      return (
-        typeof error === "object" && error !== null && "code" in error && error.code === "EPERM"
-      );
-    }
-  }
-
-  async function waitForProcessTreeExit(timeoutMsToWait: number) {
-    const deadlineAt = Date.now() + timeoutMsToWait;
-    while (Date.now() < deadlineAt) {
-      if (!processTreeAlive()) {
-        return true;
-      }
-      await new Promise((resolvePoll) => {
-        setTimeout(resolvePoll, PROCESS_GROUP_EXIT_POLL_MS);
-      });
-    }
-    return !processTreeAlive();
-  }
+  const processTreeAlive = () =>
+    inspectManagedProcessGroup(child, {
+      errorPolicy: "alive-on-eperm",
+      inspectLeaderWhenNoGroup: true,
+      platform,
+    }) === "live";
+  const waitForProcessTreeExit = (timeoutMsToWait: number) =>
+    waitForManagedProcessGroupExit(child, timeoutMsToWait, {
+      errorPolicy: "alive-on-eperm",
+      inspectLeaderWhenNoGroup: true,
+      platform,
+    });
 
   async function finishTimedOutProcessTree() {
     const graceRemainingMs =
diff --git a/test/scripts/bench-gateway-child-test-support.ts b/test/scripts/bench-gateway-child-test-support.ts
index d53f2febcace..6b8510a57d9b 100644
--- a/test/scripts/bench-gateway-child-test-support.ts
+++ b/test/scripts/bench-gateway-child-test-support.ts
@@ -1,11 +1,6 @@
 // Gateway benchmark child test support simulates child process behavior for script tests.
 import { EventEmitter } from "node:events";
 import { expect, it, vi } from "vitest";
-import { resolveWindowsTaskkillPath } from "../../scripts/lib/windows-taskkill.mjs";
-
-function expectedTaskkillPath(): string {
-  return resolveWindowsTaskkillPath();
-}
 
 type StopChildResult = {
   exitedBeforeTeardown: boolean;
@@ -17,8 +12,6 @@ type StopChild<TChild> = (
   child: TChild,
   options?: {
     killGraceMs?: number;
-    platform?: NodeJS.Platform;
-    runTaskkill?: typeof spawnSync;
     teardownGraceMs?: number;
   },
 ) => Promise<StopChildResult>;
@@ -111,116 +104,6 @@ export function registerStopChildBehaviorTests<TChild>(params: {
     expect(child.unref).toHaveBeenCalledOnce();
   });
 
-  it("signals Windows child process trees with taskkill", async () => {
-    const child = new EventEmitter() as EventEmitter & {
-      exitCode: number | null;
-      kill: ReturnType<typeof vi.fn>;
-      pid: number;
-      signalCode: NodeJS.Signals | null;
-      stderr: { destroy: ReturnType<typeof vi.fn> };
-      stdin: { destroy: ReturnType<typeof vi.fn> };
-      stdout: { destroy: ReturnType<typeof vi.fn> };
-      unref: ReturnType<typeof vi.fn>;
-    };
-    child.exitCode = null;
-    child.kill = vi.fn(() => true);
-    child.pid = 4450;
-    child.signalCode = null;
-    child.stderr = { destroy: vi.fn() };
-    child.stdin = { destroy: vi.fn() };
-    child.stdout = { destroy: vi.fn() };
-    child.unref = vi.fn();
-    const runTaskkill = vi.fn(() => ({ error: undefined, status: 0 }));
-
-    await expect(
-      params.stopChild(child as unknown as TChild, {
-        killGraceMs: 1,
-        platform: "win32",
-        runTaskkill: runTaskkill as unknown as typeof spawnSync,
-        teardownGraceMs: 1,
-      }),
-    ).resolves.toEqual({
-      exitedBeforeTeardown: false,
-      exitCode: null,
-      signal: "SIGKILL",
-    });
-    expect(runTaskkill).toHaveBeenNthCalledWith(1, expectedTaskkillPath(), ["/PID", "4450", "/T"], {
-      stdio: "ignore",
-    });
-    expect(runTaskkill).toHaveBeenNthCalledWith(
-      2,
-      expectedTaskkillPath(),
-      ["/PID", "4450", "/T", "/F"],
-      {
-        stdio: "ignore",
-      },
-    );
-    expect(child.kill).not.toHaveBeenCalled();
-    expect(child.stdin.destroy).toHaveBeenCalledOnce();
-    expect(child.stdout.destroy).toHaveBeenCalledOnce();
-    expect(child.stderr.destroy).toHaveBeenCalledOnce();
-    expect(child.unref).toHaveBeenCalledOnce();
-  });
-
-  it("force-kills Windows child process trees when graceful taskkill fails", async () => {
-    const child = new EventEmitter() as EventEmitter & {
-      exitCode: number | null;
-      kill: ReturnType<typeof vi.fn>;
-      pid: number;
-      signalCode: NodeJS.Signals | null;
-      stderr: { destroy: ReturnType<typeof vi.fn> };
-      stdin: { destroy: ReturnType<typeof vi.fn> };
-      stdout: { destroy: ReturnType<typeof vi.fn> };
-      unref: ReturnType<typeof vi.fn>;
-    };
-    child.exitCode = null;
-    child.kill = vi.fn(() => true);
-    child.pid = 4450;
-    child.signalCode = null;
-    child.stderr = { destroy: vi.fn() };
-    child.stdin = { destroy: vi.fn() };
-    child.stdout = { destroy: vi.fn() };
-    child.unref = vi.fn();
-    const runTaskkill = vi
-      .fn()
-      .mockReturnValueOnce({ error: undefined, status: 1 })
-      .mockReturnValueOnce({ error: undefined, status: 0 })
-      .mockReturnValueOnce({ error: undefined, status: 0 });
-
-    await expect(
-      params.stopChild(child as unknown as TChild, {
-        killGraceMs: 1,
-        platform: "win32",
-        runTaskkill,
-        teardownGraceMs: 1,
-      }),
-    ).resolves.toEqual({
-      exitedBeforeTeardown: false,
-      exitCode: null,
-      signal: "SIGKILL",
-    });
-    expect(runTaskkill).toHaveBeenNthCalledWith(1, expectedTaskkillPath(), ["/PID", "4450", "/T"], {
-      stdio: "ignore",
-    });
-    expect(runTaskkill).toHaveBeenNthCalledWith(
-      2,
-      expectedTaskkillPath(),
-      ["/PID", "4450", "/T", "/F"],
-      {
-        stdio: "ignore",
-      },
-    );
-    expect(runTaskkill).toHaveBeenNthCalledWith(
-      3,
-      expectedTaskkillPath(),
-      ["/PID", "4450", "/T", "/F"],
-      {
-        stdio: "ignore",
-      },
-    );
-    expect(child.kill).not.toHaveBeenCalled();
-  });
-
   it.skipIf(process.platform === "win32")(
     "preserves pre-teardown wrapper exits while cleaning the process group",
     async () => {
@@ -348,4 +231,3 @@ export function registerStopChildBehaviorTests<TChild>(params: {
     },
   );
 }
-import type { spawnSync } from "node:child_process";
diff --git a/test/scripts/dev-tooling-safety.test.ts b/test/scripts/dev-tooling-safety.test.ts
index f3b2d62d8cc9..4c20448551f6 100644
--- a/test/scripts/dev-tooling-safety.test.ts
+++ b/test/scripts/dev-tooling-safety.test.ts
@@ -22,14 +22,9 @@ import {
   redactHomePath,
   redactJsonValueForDevToolLog,
 } from "../../scripts/lib/dev-tooling-safety.ts";
-import { resolveWindowsTaskkillPath } from "../../scripts/lib/windows-taskkill.mjs";
 
 const tempDirs: string[] = [];
 
-function expectedTaskkillPath(): string {
-  return resolveWindowsTaskkillPath();
-}
-
 async function waitForCondition(predicate: () => boolean, timeoutMs = 5_000): Promise<void> {
   const started = Date.now();
   while (Date.now() - started < timeoutMs) {
@@ -501,95 +496,6 @@ describe("script-specific dev tooling hardening", () => {
     expect(retained.toString("utf8")).toBe("89abcdef");
   });
 
-  it.runIf(process.platform !== "win32")(
-    "signals the TUI PTY watch process group before falling back to the child",
-    () => {
-      const kill = vi.spyOn(process, "kill").mockReturnValue(true);
-      const childKill = vi.fn(() => true);
-
-      try {
-        tuiPtyWatchTesting.signalChildProcessTree({ pid: 123, kill: childKill }, "SIGTERM");
-        expect(kill).toHaveBeenCalledWith(-123, "SIGTERM");
-        expect(childKill).not.toHaveBeenCalled();
-      } finally {
-        kill.mockRestore();
-      }
-    },
-  );
-
-  it.runIf(process.platform !== "win32")(
-    "falls back to direct TUI PTY watch child signaling when the process group is gone",
-    () => {
-      const kill = vi.spyOn(process, "kill").mockImplementation(() => {
-        const error = new Error("missing process group") as NodeJS.ErrnoException;
-        error.code = "ESRCH";
-        throw error;
-      });
-      const childKill = vi.fn(() => true);
-
-      try {
-        tuiPtyWatchTesting.signalChildProcessTree({ pid: 123, kill: childKill }, "SIGTERM");
-        expect(kill).toHaveBeenCalledWith(-123, "SIGTERM");
-        expect(childKill).toHaveBeenCalledWith("SIGTERM");
-      } finally {
-        kill.mockRestore();
-      }
-    },
-  );
-
-  it("signals Windows TUI PTY watch process trees with taskkill", () => {
-    const childKill = vi.fn(() => true);
-    const runTaskkill = vi.fn(() => ({ error: undefined, status: 0 }));
-
-    tuiPtyWatchTesting.signalChildProcessTree({ pid: 123, kill: childKill }, "SIGTERM", {
-      platform: "win32",
-      runTaskkill,
-    });
-    expect(runTaskkill).toHaveBeenNthCalledWith(1, expectedTaskkillPath(), ["/PID", "123", "/T"], {
-      stdio: "ignore",
-    });
-
-    tuiPtyWatchTesting.signalChildProcessTree({ pid: 123, kill: childKill }, "SIGKILL", {
-      platform: "win32",
-      runTaskkill,
-    });
-    expect(runTaskkill).toHaveBeenNthCalledWith(
-      2,
-      expectedTaskkillPath(),
-      ["/PID", "123", "/T", "/F"],
-      {
-        stdio: "ignore",
-      },
-    );
-    expect(childKill).not.toHaveBeenCalled();
-  });
-
-  it("force-kills Windows TUI PTY watch process trees when graceful taskkill fails", () => {
-    const childKill = vi.fn(() => true);
-    const runTaskkill = vi
-      .fn()
-      .mockReturnValueOnce({ error: undefined, status: 1 })
-      .mockReturnValueOnce({ error: undefined, status: 0 });
-
-    tuiPtyWatchTesting.signalChildProcessTree({ pid: 123, kill: childKill }, "SIGTERM", {
-      platform: "win32",
-      runTaskkill,
-    });
-
-    expect(runTaskkill).toHaveBeenNthCalledWith(1, expectedTaskkillPath(), ["/PID", "123", "/T"], {
-      stdio: "ignore",
-    });
-    expect(runTaskkill).toHaveBeenNthCalledWith(
-      2,
-      expectedTaskkillPath(),
-      ["/PID", "123", "/T", "/F"],
-      {
-        stdio: "ignore",
-      },
-    );
-    expect(childKill).not.toHaveBeenCalled();
-  });
-
   it("aborts stalled OpenAI realtime smoke fetches at the request timeout", async () => {
     let signal: AbortSignal | undefined;
     const request = realtimeSmokeTesting.createOpenAIClientSecret("test-key", {
diff --git a/test/scripts/docker-all-scheduler.test.ts b/test/scripts/docker-all-scheduler.test.ts
index 00744f8f4940..1b71df46c6c7 100644
--- a/test/scripts/docker-all-scheduler.test.ts
+++ b/test/scripts/docker-all-scheduler.test.ts
@@ -627,9 +627,11 @@ describe("scripts/test-docker-all scheduler", () => {
     for (const fileName of [
       "docker-e2e-plan.mts",
       "docker-e2e-scenarios.mts",
+      "managed-child-process.mts",
       "official-external-channel-catalog.json",
       "release-version.mjs",
       "sleep.mjs",
+      "windows-taskkill.mjs",
     ]) {
       copyFileSync(path.join("scripts/lib", fileName), path.join(libDir, fileName));
     }
diff --git a/test/scripts/managed-child-process.test.ts b/test/scripts/managed-child-process.test.ts
index 9fbd2d01c71a..0d4490bb8989 100644
--- a/test/scripts/managed-child-process.test.ts
+++ b/test/scripts/managed-child-process.test.ts
@@ -7,9 +7,11 @@ import { pathToFileURL } from "node:url";
 import { describe, expect, it, vi } from "vitest";
 import {
   createManagedCommandSpawnSpec,
+  inspectManagedProcessGroup,
   runManagedCommand,
   signalExitCode,
   terminateManagedChild,
+  waitForManagedProcessGroupExit,
 } from "../../scripts/lib/managed-child-process.mts";
 import { createScriptTestHarness } from "./test-helpers.js";
 
@@ -199,6 +201,145 @@ describe("managed-child-process", () => {
     });
   });
 
+  it("preserves stdio-only taskkill and falls back after both trusted attempts fail", () => {
+    withDefaultWindowsSystemRoot(() => {
+      const child = { kill: vi.fn(() => true), pid: 12345 };
+      const runTaskkill = vi.fn(() => ({ error: undefined, status: 1 }));
+
+      expect(
+        terminateManagedChild(child, "SIGTERM", {
+          platform: "win32",
+          runTaskkill,
+          taskkillTimeoutMs: null,
+        }),
+      ).toEqual({ processTreeState: "indeterminate" });
+      expect(runTaskkill).toHaveBeenNthCalledWith(1, taskkillPath, ["/PID", "12345", "/T"], {
+        stdio: "ignore",
+      });
+      expect(runTaskkill).toHaveBeenNthCalledWith(2, taskkillPath, ["/PID", "12345", "/T", "/F"], {
+        stdio: "ignore",
+      });
+      expect(child.kill).toHaveBeenCalledWith("SIGTERM");
+    });
+  });
+
+  it("preserves direct Windows signaling when a caller does not own taskkill", () => {
+    const child = { kill: vi.fn(() => true), pid: 12345 };
+    const runTaskkill = vi.fn();
+
+    expect(
+      terminateManagedChild(child, "SIGTERM", {
+        platform: "win32",
+        runTaskkill,
+        useWindowsTaskkill: false,
+      }),
+    ).toEqual({ processTreeState: "signaled" });
+    expect(child.kill).toHaveBeenCalledWith("SIGTERM");
+    expect(runTaskkill).not.toHaveBeenCalled();
+  });
+
+  it("signals POSIX process groups without signaling their leaders twice", () => {
+    const kill = vi.spyOn(process, "kill").mockReturnValue(true);
+    const child = { kill: vi.fn(), pid: 12345 };
+
+    try {
+      expect(terminateManagedChild(child, "SIGTERM", { platform: "linux" })).toEqual({
+        processTreeState: "signaled",
+      });
+      expect(kill).toHaveBeenCalledWith(-12345, "SIGTERM");
+      expect(child.kill).not.toHaveBeenCalled();
+    } finally {
+      kill.mockRestore();
+    }
+  });
+
+  it.each([
+    { code: "ESRCH", processGroupFallback: "nonmissing" as const },
+    { code: "EPERM", processGroupFallback: "never" as const },
+  ])("preserves caller-owned direct fallback for $code", ({ code, processGroupFallback }) => {
+    const error = Object.assign(new Error("process group unavailable"), { code });
+    const kill = vi.spyOn(process, "kill").mockImplementation(() => {
+      throw error;
+    });
+    const child = { kill: vi.fn(), pid: 12345 };
+
+    try {
+      terminateManagedChild(child, "SIGTERM", { platform: "linux", processGroupFallback });
+      expect(child.kill).not.toHaveBeenCalled();
+    } finally {
+      kill.mockRestore();
+    }
+  });
+
+  it("preserves distinct group permission policies and verifies the leader when requested", () => {
+    const permissionError = Object.assign(new Error("group signal denied"), { code: "EPERM" });
+    const child = { exitCode: null, pid: 12345, signalCode: null };
+    const kill = vi.spyOn(process, "kill").mockImplementation((pid) => {
+      if (pid === -12345) {
+        throw permissionError;
+      }
+      return true;
+    });
+
+    try {
+      expect(
+        inspectManagedProcessGroup(child, { errorPolicy: "alive-on-eperm", platform: "linux" }),
+      ).toBe("live");
+      expect(
+        inspectManagedProcessGroup(child, { errorPolicy: "indeterminate", platform: "linux" }),
+      ).toBe("indeterminate");
+      expect(
+        inspectManagedProcessGroup(child, { errorPolicy: "verify-leader", platform: "linux" }),
+      ).toBe("live");
+      expect(kill).toHaveBeenCalledWith(12345, 0);
+      expect(
+        inspectManagedProcessGroup(
+          { ...child, exitCode: 0 },
+          { errorPolicy: "verify-leader", platform: "linux" },
+        ),
+      ).toBe("dead");
+    } finally {
+      kill.mockRestore();
+    }
+  });
+
+  it("inspects direct child liveness only when nongroup cleanup explicitly requires it", () => {
+    const child = { exitCode: null, pid: 12345, signalCode: null };
+
+    expect(
+      inspectManagedProcessGroup(child, { errorPolicy: "alive-on-eperm", platform: "win32" }),
+    ).toBe("dead");
+    expect(
+      inspectManagedProcessGroup(child, {
+        errorPolicy: "alive-on-eperm",
+        inspectLeaderWhenNoGroup: true,
+        platform: "win32",
+      }),
+    ).toBe("live");
+    expect(
+      inspectManagedProcessGroup(
+        { ...child, exitCode: 0 },
+        { errorPolicy: "alive-on-eperm", inspectLeaderWhenNoGroup: true, platform: "win32" },
+      ),
+    ).toBe("dead");
+  });
+
+  it("bounds process-group waiting when the group remains live", async () => {
+    const kill = vi.spyOn(process, "kill").mockReturnValue(true);
+
+    try {
+      await expect(
+        waitForManagedProcessGroupExit({ pid: 12345 }, 5, {
+          errorPolicy: "alive-on-eperm",
+          platform: "linux",
+          pollIntervalMs: 1,
+        }),
+      ).resolves.toBe(false);
+    } finally {
+      kill.mockRestore();
+    }
+  });
+
   it("signals the direct child when process-group ownership is disabled", () => {
     const child = { kill: vi.fn(() => true), pid: 12345 };
 
diff --git a/test/scripts/test-group-report.test.ts b/test/scripts/test-group-report.test.ts
index b58a0954b200..b4d873a4bbdd 100644
--- a/test/scripts/test-group-report.test.ts
+++ b/test/scripts/test-group-report.test.ts
@@ -13,7 +13,6 @@ import {
   resolveGroupKey,
   resolveTestArea,
 } from "../../scripts/lib/test-group-report.mts";
-import { resolveWindowsTaskkillPath } from "../../scripts/lib/windows-taskkill.mjs";
 import {
   parseTestGroupReportArgs,
   resolveFullSuiteVitestEnv,
@@ -23,7 +22,6 @@ import {
   resolveRunPlanConcurrency,
   resolveRunPlans,
   runReportPlans,
-  signalTestGroupReportChild,
   spawnText,
 } from "../../scripts/test-group-report.mts";
 import { withEnv } from "../../src/test-utils/env.js";
@@ -73,10 +71,6 @@ async function waitForDead(pid: number, timeoutMs: number): Promise<void> {
   throw new Error(`timed out waiting for pid ${pid} to exit`);
 }
 
-function expectedTaskkillPath(): string {
-  return resolveWindowsTaskkillPath();
-}
-
 function waitForChildClose(
   child: ReturnType<typeof spawn>,
   timeoutMs = 5_000,
@@ -936,75 +930,6 @@ describe("scripts/test-group-report arg parsing", () => {
 });
 
 describe("scripts/test-group-report child process guard", () => {
-  it("signals Windows child process trees with taskkill", () => {
-    const child = {
-      kill: vi.fn(),
-      pid: 12345,
-    };
-    const runTaskkill = vi.fn(() => ({ error: undefined, status: 0 }));
-
-    signalTestGroupReportChild(child, "SIGTERM", {
-      platform: "win32",
-      runTaskkill,
-    });
-    expect(runTaskkill).toHaveBeenNthCalledWith(
-      1,
-      expectedTaskkillPath(),
-      ["/PID", "12345", "/T"],
-      {
-        stdio: "ignore",
-      },
-    );
-
-    signalTestGroupReportChild(child, "SIGKILL", {
-      platform: "win32",
-      runTaskkill,
-    });
-    expect(runTaskkill).toHaveBeenNthCalledWith(
-      2,
-      expectedTaskkillPath(),
-      ["/PID", "12345", "/T", "/F"],
-      {
-        stdio: "ignore",
-      },
-    );
-    expect(child.kill).not.toHaveBeenCalled();
-  });
-
-  it("force-kills Windows child process trees when graceful taskkill fails", () => {
-    const child = {
-      kill: vi.fn(),
-      pid: 12345,
-    };
-    const runTaskkill = vi
-      .fn()
-      .mockReturnValueOnce({ error: undefined, status: 1 })
-      .mockReturnValueOnce({ error: undefined, status: 0 });
-
-    signalTestGroupReportChild(child, "SIGTERM", {
-      platform: "win32",
-      runTaskkill,
-    });
-
-    expect(runTaskkill).toHaveBeenNthCalledWith(
-      1,
-      expectedTaskkillPath(),
-      ["/PID", "12345", "/T"],
-      {
-        stdio: "ignore",
-      },
-    );
-    expect(runTaskkill).toHaveBeenNthCalledWith(
-      2,
-      expectedTaskkillPath(),
-      ["/PID", "12345", "/T", "/F"],
-      {
-        stdio: "ignore",
-      },
-    );
-    expect(child.kill).not.toHaveBeenCalled();
-  });
-
   it.concurrent("times out a child that ignores SIGTERM", async () => {
     if (process.platform === "win32") {
       return;

From 8c0cdc653559f5009d89d9180497d2c77c000848 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 15:51:45 -0700
Subject: [PATCH 121/124] fix(gateway): reject unconfigured session owners
 (#127661)

Validate the canonical configured owner before session and worktree side effects so dispatch, reclaim, and delete can manage every created session.
---
 src/gateway/server-methods/sessions-create.ts | 34 ++-------
 src/gateway/server.sessions.create.test.ts    | 35 +++++++++-
 ...sessions.delete-worktree-lifecycle.test.ts | 69 +++++++++++++++++++
 src/gateway/session-create-service.ts         | 49 ++++---------
 src/gateway/session-request-agent.ts          | 13 +---
 5 files changed, 124 insertions(+), 76 deletions(-)

diff --git a/src/gateway/server-methods/sessions-create.ts b/src/gateway/server-methods/sessions-create.ts
index 2aafe0e8a605..ba7ef82c0000 100644
--- a/src/gateway/server-methods/sessions-create.ts
+++ b/src/gateway/server-methods/sessions-create.ts
@@ -33,7 +33,6 @@ import {
   resolveSessionCreateModelSelection as resolveCreateTitleEntry,
 } from "../session-create-service.js";
 import { resolveRequestedSessionAgentId as resolveRequestedGlobalAgentId } from "../session-request-agent.js";
-import { resolveSessionStoreAgentId } from "../session-store-key.js";
 import { readSessionMessageCountAsync } from "../session-transcript-readers.js";
 import {
   loadGatewaySessionEntryReadOnly,
@@ -104,8 +103,7 @@ export const sessionCreateHandlers: GatewayRequestHandlers = {
     const explicitlyRequestedAgent = resolveRequestedGlobalAgentId(
       cfg,
       agentSelectionKey,
-      explicitlyRequestedAgentId,
-      { allowUnconfiguredExplicitAgent: true },
+      p.agentId ?? parseAgentSessionKey(explicitlyRequestedKey)?.agentId,
     );
     if (!explicitlyRequestedAgent.ok) {
       respond(false, undefined, explicitlyRequestedAgent.error);
@@ -224,7 +222,7 @@ export const sessionCreateHandlers: GatewayRequestHandlers = {
       return;
     }
     const explicitSessionLabel = normalizeOptionalString(p.label);
-    const titleAgentId = normalizeAgentId(explicitlyRequestedAgent.agentId);
+    const titleAgentId = explicitlyRequestedAgent.agentId;
     const shouldPrepareWorktreeTitle =
       p.worktree === true && !requestedWorktreeName && !explicitSessionLabel;
     const deferWorktreeTitle =
@@ -280,11 +278,7 @@ export const sessionCreateHandlers: GatewayRequestHandlers = {
       }
     }
     let sessionKey = p.key;
-    let sessionAgentId =
-      catalogAgentId ??
-      explicitlyRequestedAgent.agentId ??
-      p.agentId ??
-      parseAgentSessionKey(explicitlyRequestedKey)?.agentId;
+    let sessionAgentId = catalogAgentId ?? explicitlyRequestedAgent.agentId;
     let sessionWorktree: Awaited<ReturnType<typeof managedWorktrees.create>> | undefined;
     const sessionExecCwd = requestedExecNode ? requestedCwd : undefined;
     let sessionCwd = requestedExecNode ? undefined : (projectRoot ?? requestedCwd);
@@ -298,11 +292,7 @@ export const sessionCreateHandlers: GatewayRequestHandlers = {
       requestedProjectId,
       sessionCwd,
       sessionKey,
-      targetAgentId: normalizeAgentId(
-        sessionAgentId ??
-          parseAgentSessionKey(sessionKey ?? "")?.agentId ??
-          explicitlyRequestedAgent.agentId,
-      ),
+      targetAgentId: sessionAgentId,
     });
     if (!preparedRoot.ok) {
       respond(false, undefined, preparedRoot.error);
@@ -314,11 +304,7 @@ export const sessionCreateHandlers: GatewayRequestHandlers = {
       // Workspace-contained cwd and registry-authorized projects stay at operator.write;
       // arbitrary host paths still require operator.admin before reaching this block.
       const explicitKey = explicitlyRequestedKey;
-      const agentId = normalizeAgentId(
-        explicitlyRequestedAgent.agentId ??
-          normalizeOptionalString(p.agentId) ??
-          parseAgentSessionKey(explicitKey)?.agentId,
-      );
+      const agentId = explicitlyRequestedAgent.agentId;
       let targetKey = explicitKey;
       let preservesUnspecifiedKey = false;
       if (
@@ -336,9 +322,7 @@ export const sessionCreateHandlers: GatewayRequestHandlers = {
         const parent = loadGatewaySessionEntryReadOnly(parentSessionKey, {
           agentId: parentRequestedAgent.agentId,
         });
-        const parentAgentId = normalizeAgentId(
-          parentRequestedAgent.agentId ?? resolveSessionStoreAgentId(cfg, parent.canonicalKey),
-        );
+        const parentAgentId = parentRequestedAgent.agentId;
         if (
           parent.entry?.sessionId &&
           parent.canonicalKey === resolveAgentMainSessionKey({ cfg, agentId: parentAgentId })
@@ -518,11 +502,7 @@ export const sessionCreateHandlers: GatewayRequestHandlers = {
       ADMIN_SCOPE,
       clientScopes,
     ).allowed;
-    const modelCatalogAgentId = normalizeAgentId(
-      sessionAgentId ??
-        parseAgentSessionKey(sessionKey ?? "")?.agentId ??
-        explicitlyRequestedAgent.agentId,
-    );
+    const modelCatalogAgentId = sessionAgentId;
     if (!authority.ensureActive()) {
       return;
     }
diff --git a/src/gateway/server.sessions.create.test.ts b/src/gateway/server.sessions.create.test.ts
index 4f5cfa5025ad..fc99cde4b9bc 100644
--- a/src/gateway/server.sessions.create.test.ts
+++ b/src/gateway/server.sessions.create.test.ts
@@ -748,6 +748,30 @@ test("incognito webchat rejects a vanished non-default-agent session before disp
   }
 });
 
+test("createGatewaySession rejects explicit and key-derived unconfigured creation owners", async () => {
+  const { createGatewaySession } = await import("./session-create-service.js");
+  const cfg = { agents: { entries: { ops: { default: true } } } };
+  const prepareLifecycle = vi.fn();
+
+  for (const { owner, message } of [
+    { owner: { agentId: "main" }, message: 'Unknown agent id "main"' },
+    {
+      owner: { key: "agent:main:dashboard:unconfigured-owner" },
+      message: 'Unknown agent id "main"',
+    },
+    { owner: { agentId: "   " }, message: 'Unknown agent id "   "' },
+  ]) {
+    await expect(
+      createGatewaySession({ cfg, ...owner, commandSource: "test", prepareLifecycle }),
+    ).resolves.toMatchObject({
+      ok: false,
+      error: { code: "INVALID_REQUEST", message },
+    });
+  }
+
+  expect(prepareLifecycle).not.toHaveBeenCalled();
+});
+
 test("createGatewaySession rechecks admin scope after incognito inheritance resolves", async () => {
   await createSessionStoreDir();
   try {
@@ -2879,6 +2903,7 @@ test("sessions.create rejects worktrees for agent workspaces without a commit",
 
 test("sessions.create stores dashboard model, thinking, and parent linkage, and creates a transcript", async () => {
   const { storePath } = await createSessionStoreDir();
+  testState.agentsConfig = { list: [{ id: "main", default: true }, { id: "ops" }] };
   agentDiscoveryMock.enabled = true;
   agentDiscoveryMock.models = [{ id: "gpt-test-a", name: "A", provider: "openai" }];
   await writeSessionStore({
@@ -3737,6 +3762,7 @@ test("sessions.create resolves the current default instead of inherited runtime
 
 test("sessions.create accepts an explicit key for persistent dashboard sessions", async () => {
   await createSessionStoreDir();
+  testState.agentsConfig = { list: [{ id: "main", default: true }, { id: "ops-agent" }] };
 
   const key = "agent:ops-agent:dashboard:direct:subagent-orchestrator";
   const created = await directSessionReq<{
@@ -4120,6 +4146,8 @@ test("sessions.create adopting an existing key does not restamp node provenance"
 
 test("sessions.create scopes the main alias to the requested agent", async () => {
   const { storePath } = await createSessionStoreDir();
+  testState.agentsConfig = { list: [{ id: "main", default: true }, { id: "longmemeval" }] };
+  testState.agentConfig = { sessionStore: { agentId: "longmemeval" } };
 
   const created = await directSessionReq<{
     key?: string;
@@ -4132,7 +4160,7 @@ test("sessions.create scopes the main alias to the requested agent", async () =>
     agentId: "longmemeval",
   });
 
-  expect(created.ok).toBe(true);
+  expect(created.ok, JSON.stringify(created.error)).toBe(true);
   expect(created.payload?.key).toBe("agent:longmemeval:main");
   expect(created.payload?.entry).not.toHaveProperty("sessionFile");
 
@@ -4197,6 +4225,8 @@ test("sessions.create replaces a dead main entry with a fresh session id", async
 
 test("sessions.create preserves global and unknown sentinel keys", async () => {
   const { storePath } = await createSessionStoreDir();
+  testState.agentsConfig = { list: [{ id: "main", default: true }, { id: "longmemeval" }] };
+  testState.agentConfig = { sessionStore: { agentId: "longmemeval" } };
 
   const globalCreated = await directSessionReq<{
     key?: string;
@@ -4209,7 +4239,7 @@ test("sessions.create preserves global and unknown sentinel keys", async () => {
     agentId: "longmemeval",
   });
 
-  expect(globalCreated.ok).toBe(true);
+  expect(globalCreated.ok, JSON.stringify(globalCreated.error)).toBe(true);
   expect(globalCreated.payload?.key).toBe("global");
   expect(globalCreated.payload?.entry).not.toHaveProperty("sessionFile");
 
@@ -4646,6 +4676,7 @@ test("sessions.create allows plugin runtimes to link their own parent session",
 
 test("sessions.create rejects unknown parentSessionKey", async () => {
   await createSessionStoreDir();
+  testState.agentsConfig = { list: [{ id: "main", default: true }, { id: "ops" }] };
 
   const created = await directSessionReq("sessions.create", {
     agentId: "ops",
diff --git a/src/gateway/server.sessions.delete-worktree-lifecycle.test.ts b/src/gateway/server.sessions.delete-worktree-lifecycle.test.ts
index 791b6c1f30d1..41984aecc502 100644
--- a/src/gateway/server.sessions.delete-worktree-lifecycle.test.ts
+++ b/src/gateway/server.sessions.delete-worktree-lifecycle.test.ts
@@ -53,6 +53,75 @@ async function initializeRemoteBackedGitWorkspace(root: string): Promise<string>
   return await fs.realpath(workspace);
 }
 
+test("sessions.create only allocates worktrees for lifecycle-manageable agent owners", async () => {
+  const openClawState = await createOpenClawTestState({
+    layout: "state-only",
+    prefix: "openclaw-create-worktree-agent-owner-",
+  });
+  const workspace = await initializeRemoteBackedGitWorkspace(openClawState.root);
+  closeOpenClawStateDatabaseForTest();
+  testState.agentConfig = { workspace };
+  testState.agentsConfig = { list: [{ id: "ops", default: true }] };
+  const { storePath } = await createSessionStoreDir();
+  const adminClient = { connect: { scopes: ["operator.admin"] } } as never;
+  const allocatedWorktreeIds = new Set<string>();
+  const createWorktree = vi.spyOn(managedWorktrees, "create");
+  try {
+    for (const owner of [{ agentId: "main" }, { key: "agent:main:dashboard:unconfigured-owner" }]) {
+      const created = await directSessionReq<{
+        key: string;
+        worktree: { id: string };
+      }>("sessions.create", { ...owner, worktree: true }, { client: adminClient });
+      if (created.payload?.worktree.id) {
+        allocatedWorktreeIds.add(created.payload.worktree.id);
+      }
+
+      expect(created).toMatchObject({
+        ok: false,
+        error: { code: "INVALID_REQUEST", message: 'Unknown agent id "main"' },
+      });
+      if (owner.key) {
+        expect(
+          loadSessionEntry({ agentId: "main", sessionKey: owner.key, storePath }),
+        ).toBeUndefined();
+      }
+      expect(createWorktree).not.toHaveBeenCalled();
+    }
+
+    for (const owner of [{ agentId: "ops" }, {}]) {
+      const created = await directSessionReq<{
+        key: string;
+        worktree: { id: string; path: string };
+      }>("sessions.create", { ...owner, worktree: true }, { client: adminClient });
+      if (created.payload?.worktree.id) {
+        allocatedWorktreeIds.add(created.payload.worktree.id);
+      }
+      expect(created).toMatchObject({
+        ok: true,
+        payload: { key: expect.stringMatching(/^agent:ops:/) },
+      });
+
+      const worktree = created.payload!.worktree;
+      await expect(
+        directSessionReq("sessions.delete", { key: created.payload!.key, agentId: "ops" }),
+      ).resolves.toMatchObject({ ok: true, payload: { deleted: true } });
+      await expect(fs.access(worktree.path)).rejects.toThrow();
+      allocatedWorktreeIds.delete(worktree.id);
+    }
+  } finally {
+    createWorktree.mockRestore();
+    for (const id of allocatedWorktreeIds) {
+      if (getRegistryWorktree(process.env, id)?.removedAt === undefined) {
+        await managedWorktrees.remove({ id, reason: "test-cleanup", allowSnapshotLoss: true });
+      }
+    }
+    closeOpenClawStateDatabaseForTest();
+    testState.agentConfig = undefined;
+    testState.agentsConfig = undefined;
+    await openClawState.cleanup();
+  }
+});
+
 test("sessions.delete snapshots and removes session worktrees", async () => {
   const openClawState = await createOpenClawTestState({
     layout: "state-only",
diff --git a/src/gateway/session-create-service.ts b/src/gateway/session-create-service.ts
index d9876f3ad1f5..944ea6e8a971 100644
--- a/src/gateway/session-create-service.ts
+++ b/src/gateway/session-create-service.ts
@@ -345,44 +345,21 @@ export async function createGatewaySession(params: {
   const requestedKey = normalizeOptionalString(params.key);
   const parentSessionKey = normalizeOptionalString(params.parentSessionKey);
   const projectId = normalizeOptionalString(params.projectId);
-  const explicitAgentId = normalizeOptionalString(params.agentId);
+  const explicitAgentId = params.agentId;
+  const normalizedExplicitAgentId = normalizeOptionalString(explicitAgentId);
   const explicitKeyAgentId = parseAgentSessionKey(requestedKey)?.agentId;
-  if (
-    explicitAgentId &&
-    explicitKeyAgentId &&
-    normalizeAgentId(explicitKeyAgentId) !== normalizeAgentId(explicitAgentId)
-  ) {
-    return {
-      ok: false,
-      error: errorShape(
-        ErrorCodes.INVALID_REQUEST,
-        `sessions.create key agent (${explicitKeyAgentId}) does not match agentId (${normalizeAgentId(explicitAgentId)})`,
-      ),
-    };
-  }
-  const requestedKeyAgent = requestedKey
-    ? resolveRequestedSessionAgentId(params.cfg, requestedKey, explicitAgentId, {
-        allowUnconfiguredExplicitAgent: true,
-      })
-    : undefined;
-  if (requestedKeyAgent && !requestedKeyAgent.ok) {
-    return requestedKeyAgent;
-  }
-  // Resolve the main alias under an explicit selection before compatibility ownership.
-  const implicitSelectionKey = explicitAgentId
-    ? `agent:${normalizeAgentId(explicitAgentId)}:main`
-    : "main";
-  const implicitAgent = requestedKeyAgent
-    ? undefined
-    : resolveRequestedSessionAgentId(params.cfg, implicitSelectionKey, explicitAgentId, {
-        allowUnconfiguredExplicitAgent: true,
-      });
-  if (implicitAgent && !implicitAgent.ok) {
-    return implicitAgent;
-  }
-  const agentId = normalizeAgentId(
-    explicitAgentId ?? requestedKeyAgent?.agentId ?? implicitAgent?.agentId,
+  const selectedAgent = resolveRequestedSessionAgentId(
+    params.cfg,
+    requestedKey ??
+      (normalizedExplicitAgentId
+        ? `agent:${normalizeAgentId(normalizedExplicitAgentId)}:main`
+        : "main"),
+    explicitAgentId ?? explicitKeyAgentId,
   );
+  if (!selectedAgent.ok) {
+    return selectedAgent;
+  }
+  const agentId = selectedAgent.agentId;
   const catalogModel = normalizeOptionalString(params.catalogTarget?.model);
   const catalogAgentRuntime = normalizeOptionalAgentRuntimeId(params.catalogTarget?.agentRuntime);
   const catalogPluginOwnerId = normalizeOptionalString(params.catalogTarget?.pluginOwnerId);
diff --git a/src/gateway/session-request-agent.ts b/src/gateway/session-request-agent.ts
index a0b3b1a44a76..7344b22dbeb8 100644
--- a/src/gateway/session-request-agent.ts
+++ b/src/gateway/session-request-agent.ts
@@ -36,7 +36,6 @@ export function resolveRequestedSessionAgentId(
   cfg: OpenClawConfig,
   key: string,
   explicitAgentId?: string,
-  options?: { allowUnconfiguredExplicitAgent?: boolean },
 ): RequestedSessionAgentIdResolution {
   const parsed = parseAgentSessionKey(key.trim());
   const configuredAgentIds = listAgentIds(cfg);
@@ -49,11 +48,7 @@ export function resolveRequestedSessionAgentId(
     };
   }
   const normalizedRequestedAgentId = normalizedRequest?.value;
-  if (
-    normalizedRequestedAgentId &&
-    !options?.allowUnconfiguredExplicitAgent &&
-    !configuredAgentIds.includes(normalizedRequestedAgentId)
-  ) {
+  if (normalizedRequestedAgentId && !configuredAgentIds.includes(normalizedRequestedAgentId)) {
     return {
       ok: false,
       error: errorShape(ErrorCodes.INVALID_REQUEST, `Unknown agent id "${explicitAgentId}"`),
@@ -64,11 +59,7 @@ export function resolveRequestedSessionAgentId(
     const keyIsGlobalMainAlias =
       cfg.session?.scope === "global" &&
       (parsed.rest === "main" || parsed.rest === normalizeMainKey(cfg.session?.mainKey));
-    if (
-      keyIsGlobalMainAlias &&
-      !options?.allowUnconfiguredExplicitAgent &&
-      !configuredAgentIds.includes(keyAgentId)
-    ) {
+    if (keyIsGlobalMainAlias && !configuredAgentIds.includes(keyAgentId)) {
       return {
         ok: false,
         error: errorShape(ErrorCodes.INVALID_REQUEST, `Unknown agent id "${parsed.agentId}"`),

From 11081a95b83663511d8faf6d08144d61ee7fd43b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 15:54:24 -0700
Subject: [PATCH 122/124] test: remove final moving-tip duplicates (#126990)

---
 .../OnboardingViewSmokeTests.swift            |  7 +-
 .../auth-profiles/paths-direct-import.test.ts | 13 +---
 src/cli/qr-cli.test.ts                        | 33 ---------
 .../app-host-onboarding-memory-import.test.ts | 67 -------------------
 4 files changed, 2 insertions(+), 118 deletions(-)
 delete mode 100644 ui/src/app/app-host-onboarding-memory-import.test.ts

diff --git a/apps/macos/Tests/OpenClawIPCTests/OnboardingViewSmokeTests.swift b/apps/macos/Tests/OpenClawIPCTests/OnboardingViewSmokeTests.swift
index 348d98ecd917..6499f478b028 100644
--- a/apps/macos/Tests/OpenClawIPCTests/OnboardingViewSmokeTests.swift
+++ b/apps/macos/Tests/OpenClawIPCTests/OnboardingViewSmokeTests.swift
@@ -139,12 +139,7 @@ struct OnboardingViewSmokeTests {
         #expect(!order.contains(2))
     }
 
-    @Test func `fresh remote setup installs CLI for the Mac node worker`() {
-        let order = OnboardingView.pageOrder(
-            for: .remote,
-            requiresCLIInstall: true)
-
-        #expect(order.contains(2))
+    @Test func `CLI install activates only a local gateway`() {
         #expect(!OnboardingView.shouldActivateLocalGateway(afterCLIInstallFor: .remote))
         #expect(OnboardingView.shouldActivateLocalGateway(afterCLIInstallFor: .local))
     }
diff --git a/src/agents/auth-profiles/paths-direct-import.test.ts b/src/agents/auth-profiles/paths-direct-import.test.ts
index bdb0d5bcd9a2..3e5f377d6d57 100644
--- a/src/agents/auth-profiles/paths-direct-import.test.ts
+++ b/src/agents/auth-profiles/paths-direct-import.test.ts
@@ -12,8 +12,7 @@ import {
 } from "../../commands/doctor-auth-legacy-paths.js";
 import { withEnv } from "../../test-utils/env.js";
 import { resolveSharedAuthStorePath } from "./path-resolve.js";
-import { resolveAuthStatePathForDisplay, resolveAuthStorePathForDisplay } from "./paths.js";
-import { writePersistedAuthProfileStoreRaw } from "./sqlite.js";
+import { resolveAuthStorePathForDisplay } from "./paths.js";
 
 const tempDirs = useAutoCleanupTempDirTracker(afterEach);
 
@@ -78,16 +77,6 @@ describe("auth profile path helpers (direct-import coverage attribution)", () =>
     });
   });
 
-  it("uses one database path for an agent-local auth store and its runtime state", () => {
-    const agentDir = path.join(stateDir, "agents", "main", "agent");
-    withEnv({ OPENCLAW_STATE_DIR: stateDir }, () => {
-      writePersistedAuthProfileStoreRaw({ version: 1, profiles: {} }, agentDir);
-      const expectedPath = path.join(agentDir, "openclaw-agent.sqlite");
-      expect(resolveAuthStorePathForDisplay(agentDir)).toBe(expectedPath);
-      expect(resolveAuthStatePathForDisplay(agentDir)).toBe(expectedPath);
-    });
-  });
-
   it("falls back to the shared owner for an agent dir that has no local store", () => {
     withEnv({ OPENCLAW_STATE_DIR: stateDir }, () => {
       // A tilde-rooted dir resolveUserPath cannot expand still must not be reported as the owner:
diff --git a/src/cli/qr-cli.test.ts b/src/cli/qr-cli.test.ts
index 7b25b1e07b03..ef6b2cf72715 100644
--- a/src/cli/qr-cli.test.ts
+++ b/src/cli/qr-cli.test.ts
@@ -7,8 +7,6 @@ import {
   PAIRING_SETUP_BOOTSTRAP_PROFILE,
   VOICE_NODE_PAIRING_SETUP_BOOTSTRAP_PROFILE,
 } from "../shared/device-bootstrap-profile.js";
-import { formatCliJsonFailure } from "./failure-output.js";
-import { runCliWithExitFinalization } from "./one-shot-exit.js";
 import { createCliRuntimeCapture, mockRuntimeModule } from "./test-runtime-capture.js";
 
 const mocks = vi.hoisted(() => ({
@@ -287,37 +285,6 @@ describe("registerQrCli", () => {
     expect(loadConfig).not.toHaveBeenCalled();
   });
 
-  it.each(conflictingQrOptions)("renders conflicting $name as canonical JSON", async (testCase) => {
-    const args = ["--json", ...testCase.args];
-    const originalArgv = process.argv;
-    let exitCode: number | undefined;
-    process.argv = ["node", "openclaw", "qr", ...args];
-    try {
-      await runCliWithExitFinalization({
-        runtime,
-        run: async () => await runQr(args),
-        onError: (error) => {
-          runtime.writeJson(formatCliJsonFailure(error));
-          exitCode = 1;
-        },
-      });
-    } finally {
-      process.argv = originalArgv;
-    }
-
-    const expected = {
-      ok: false,
-      error: { type: "cli_error", message: testCase.message },
-    };
-    expect(exitCode).toBe(1);
-    expect(runtime.writeJson).toHaveBeenCalledExactlyOnceWith(expected);
-    expect(runtimeLog).toHaveBeenCalledOnce();
-    expect(JSON.parse(readRuntimeCallText(runtimeLog.mock.calls[0]))).toEqual(expected);
-    expect(runtimeError).not.toHaveBeenCalled();
-    expect(runtimeExit).not.toHaveBeenCalled();
-    expect(loadConfig).not.toHaveBeenCalled();
-  });
-
   it("renders ASCII QR by default", async () => {
     loadConfig.mockReturnValue({
       gateway: {
diff --git a/ui/src/app/app-host-onboarding-memory-import.test.ts b/ui/src/app/app-host-onboarding-memory-import.test.ts
deleted file mode 100644
index 5fa7dea7e8db..000000000000
--- a/ui/src/app/app-host-onboarding-memory-import.test.ts
+++ /dev/null
@@ -1,67 +0,0 @@
-/* @vitest-environment jsdom */
-
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { waitForFast } from "../test-helpers/wait-for.ts";
-import {
-  createLazyElementSpec,
-  resetAppHostTestGlobals,
-  type TestOptionalCustomElement,
-} from "./app-host.test-support.ts";
-import "./app-host.ts";
-import type { LazyCustomElementRequestController } from "./lazy-custom-element.ts";
-
-type ShellOnboardingMemoryImportState = {
-  onboardingMemoryImportElement: TestOptionalCustomElement;
-  lazyCustomElements: LazyCustomElementRequestController;
-};
-
-afterEach(() => resetAppHostTestGlobals());
-
-describe("OpenClaw shell onboarding memory import", () => {
-  it("surfaces a rejected load and retries it", async () => {
-    const element = createLazyElementSpec("onboarding memory import", {
-      firstError: new Error("memory import chunk unavailable"),
-    });
-    const shell = document.createElement(
-      "openclaw-app-shell",
-    ) as unknown as ShellOnboardingMemoryImportState;
-    shell.onboardingMemoryImportElement = element;
-    Object.defineProperty(shell, "updateComplete", { get: () => Promise.resolve(true) });
-
-    shell.lazyCustomElements.requestWhileActive(element, true);
-
-    await waitForFast(() => expect(shell.lazyCustomElements.visibleState?.status).toBe("error"));
-    expect(shell.lazyCustomElements.visibleState?.element).toBe(element);
-    shell.lazyCustomElements.retry();
-    await waitForFast(() => expect(customElements.get(element.tagName)).toBeDefined());
-    expect(shell.lazyCustomElements.visibleState).toBeUndefined();
-  });
-
-  it("abandons a pending load when onboarding ends", async () => {
-    let rejectLoad: ((error: Error) => void) | undefined;
-    let loadSettled: Promise<void> | undefined;
-    const element = createLazyElementSpec("onboarding memory import");
-    element.loadModule = vi.fn(() => {
-      const load = new Promise<void>((_resolve, reject) => {
-        rejectLoad = reject;
-      });
-      loadSettled = load.catch(() => undefined);
-      return load;
-    });
-    const shell = document.createElement(
-      "openclaw-app-shell",
-    ) as unknown as ShellOnboardingMemoryImportState;
-    shell.onboardingMemoryImportElement = element;
-
-    shell.lazyCustomElements.requestWhileActive(element, true);
-    await waitForFast(() => expect(element.loadModule).toHaveBeenCalledOnce());
-    expect(shell.lazyCustomElements.visibleState?.status).toBe("loading");
-    shell.lazyCustomElements.requestWhileActive(element, false);
-    const error = new Error("late memory import chunk failure");
-    rejectLoad?.(error);
-    await loadSettled;
-    await Promise.resolve();
-
-    expect(shell.lazyCustomElements.visibleState).toBeUndefined();
-  });
-});

From a7a68cfb47a1ac099910dbe65e31921089902840 Mon Sep 17 00:00:00 2001
From: Alix-007 <li.long15@xydigit.com>
Date: Sat, 22 Aug 2026 06:56:10 +0800
Subject: [PATCH 123/124] fix(ui): keep annotated slash commands local
 (#121191)

* fix(ui): keep browser annotations out of commands

* fix(ui): reuse raw command classification

* fix(ui): fence retained browser annotations by exact identity

Preserve the authoritative annotation object during slash-command recovery and prove terminal command retirement, restored screenshot and document bytes, and same-ID replacement races.

Co-authored-by: Alix-007 <li.long15@xydigit.com>

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 ui/src/e2e/chat-flow.messaging.e2e.test.ts |  24 ++-
 ui/src/pages/chat/chat-send-composer.ts    |  41 +++-
 ui/src/pages/chat/chat-send-submit.test.ts | 238 ++++++++++++++++++++-
 ui/src/pages/chat/chat-send-submit.ts      |  42 ++--
 4 files changed, 316 insertions(+), 29 deletions(-)

diff --git a/ui/src/e2e/chat-flow.messaging.e2e.test.ts b/ui/src/e2e/chat-flow.messaging.e2e.test.ts
index eb4a35640af0..63ddf2374ddf 100644
--- a/ui/src/e2e/chat-flow.messaging.e2e.test.ts
+++ b/ui/src/e2e/chat-flow.messaging.e2e.test.ts
@@ -766,7 +766,7 @@ suite.define(() => {
     });
   });
 
-  it("sends /stop to the exact selected channel session and clears its working indicator", async () => {
+  it("sends annotated /stop to the exact selected channel session and clears its working indicator", async () => {
     await withChatPage(async (page) => {
       const channelSessionKey = "agent:main:openclaw-weixin:direct:wechat-user";
       const gateway = await installMockGateway(page, {
@@ -792,6 +792,27 @@ suite.define(() => {
       const workingIndicator = page.locator(".chat-working-indicator");
       await workingIndicator.waitFor({ state: "visible", timeout: 10_000 });
 
+      await page.evaluate(() => {
+        window.dispatchEvent(
+          new CustomEvent("openclaw:browser-annotation", {
+            cancelable: true,
+            detail: {
+              modelContext: "Review the annotated page",
+              dataUrl:
+                "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/woAAn8B9FD5fHAAAAAASUVORK5CYII=",
+              fileName: "annotated-page.png",
+              card: {
+                title: "Annotated page",
+                displayUrl: "example.com",
+                markedRegionCount: 1,
+                inspectedElement: false,
+              },
+            },
+          }),
+        );
+      });
+      await page.locator(".chat-attachment-thumb--browser-annotation").waitFor();
+
       await composer.fill("/stop");
       await page.getByRole("option", { name: /\/stop/ }).waitFor();
       await composer.press("Enter");
@@ -824,6 +845,7 @@ suite.define(() => {
         updatedAt: Date.now(),
       });
       await workingIndicator.waitFor({ state: "detached", timeout: 10_000 });
+      await page.locator(".chat-attachment-thumb--browser-annotation").waitFor();
       await expectRequestCountStable(gateway, "chat.abort", 0);
       await expectRequestCountStable(gateway, "chat.send", 0);
       await expect.poll(() => page.getByRole("listbox").count()).toBe(0);
diff --git a/ui/src/pages/chat/chat-send-composer.ts b/ui/src/pages/chat/chat-send-composer.ts
index 809cf008f7c1..11e34f0022fc 100644
--- a/ui/src/pages/chat/chat-send-composer.ts
+++ b/ui/src/pages/chat/chat-send-composer.ts
@@ -104,6 +104,22 @@ export function commandComposerFallbackRetainsAttachments(
   );
 }
 
+function composerRetainsSubmittedAnnotations(
+  host: ChatHost,
+  submittedAttachments?: readonly ChatAttachment[],
+): boolean {
+  const retained = submittedAttachments?.filter((attachment) => attachment.browserAnnotation);
+  return Boolean(
+    retained?.length &&
+    retained.length === host.chatAttachments.length &&
+    retained.every(
+      (attachment, index) =>
+        attachment.id === host.chatAttachments[index]?.id &&
+        attachment.browserAnnotation === host.chatAttachments[index]?.browserAnnotation,
+    ),
+  );
+}
+
 export function restoreFailedCommandComposer(
   host: ChatHost,
   recovery: ChatCommandComposerRecovery,
@@ -129,7 +145,10 @@ export function restoreFailedCommandComposer(
     composer.fallbackOwnership = ownership;
     return composer.attachments.length === 0 || ownership !== undefined;
   }
-  if (host.chatAttachments.length > 0) {
+  if (
+    host.chatAttachments.length > 0 &&
+    !composerRetainsSubmittedAnnotations(host, composer.attachments)
+  ) {
     clearOwnedCommandComposerFallback(host, recovery);
     return composer.attachments.length === 0;
   }
@@ -157,11 +176,12 @@ type PendingComposerSnapshot = {
 
 function strictComposerRestore(host: ChatHost, snapshot: PendingComposerSnapshot) {
   // An attachment-only edit is still a newer draft. Restoring old text beside it
-  // would combine two independently authored sends.
-  const composerBlank = !host.chatMessage.trim() && host.chatAttachments.length === 0;
-  const attachments = Boolean(
-    snapshot.previousAttachments?.length && host.chatAttachments.length === 0 && composerBlank,
-  );
+  // would combine sends; annotations retained by this exact command are not edits.
+  const composerBlank =
+    !host.chatMessage.trim() &&
+    (host.chatAttachments.length === 0 ||
+      composerRetainsSubmittedAnnotations(host, snapshot.previousAttachments));
+  const attachments = Boolean(snapshot.previousAttachments?.length && composerBlank);
   return { attachments, draft: snapshot.previousDraft != null && composerBlank };
 }
 
@@ -169,7 +189,11 @@ export function restoreComposer(host: ChatHost, snapshot: PendingComposerSnapsho
   if (snapshot.previousDraft != null && !host.chatMessage.trim()) {
     host.chatMessage = snapshot.previousDraft;
   }
-  if (snapshot.previousAttachments?.length && host.chatAttachments.length === 0) {
+  if (
+    snapshot.previousAttachments?.length &&
+    (host.chatAttachments.length === 0 ||
+      composerRetainsSubmittedAnnotations(host, snapshot.previousAttachments))
+  ) {
     host.chatAttachments = snapshot.previousAttachments;
   }
 }
@@ -209,7 +233,8 @@ function pendingComposerRestorePlan(host: ChatHost, snapshot: PendingComposerSna
   const willRestoreDraft = snapshot.previousDraft != null && !host.chatMessage.trim();
   const willRestoreAttachments = Boolean(
     snapshot.previousAttachments?.length &&
-    host.chatAttachments.length === 0 &&
+    (host.chatAttachments.length === 0 ||
+      composerRetainsSubmittedAnnotations(host, snapshot.previousAttachments)) &&
     (willRestoreDraft || !host.chatMessage.trim()),
   );
   return {
diff --git a/ui/src/pages/chat/chat-send-submit.test.ts b/ui/src/pages/chat/chat-send-submit.test.ts
index 7705e5f1349e..9d6d40d8694e 100644
--- a/ui/src/pages/chat/chat-send-submit.test.ts
+++ b/ui/src/pages/chat/chat-send-submit.test.ts
@@ -162,11 +162,11 @@ describe("handleSendChat browser annotation context", () => {
     expect(findChatSendPayload(host).message).toBe("Inspect this page");
   });
 
-  it("treats a slash-prefixed draft with an annotation as model input", async () => {
+  it("routes /new before materializing annotation context", async () => {
     const attachment = createBrowserAnnotationAttachment("slash", "Review the annotated page");
     const createChatSession = vi.fn(async () => true);
     const host = makeChatHost({
-      requestHandlers: { "chat.send": { runId: "annotation-slash-run", status: "started" } },
+      requestHandlers: {},
       chatAttachments: [attachment],
       chatMessage: "/new",
       createChatSession,
@@ -174,9 +174,237 @@ describe("handleSendChat browser annotation context", () => {
 
     await handleSendChat(host);
 
-    expect(createChatSession).not.toHaveBeenCalled();
-    expect(findChatSendPayload(host).message).toBe("Review the annotated page\n\n/new");
-    expect(host.chatLocalInputHistoryBySession[host.sessionKey]?.[0]?.text).toBe("/new");
+    expect(createChatSession).toHaveBeenCalledOnce();
+    expect(host.request).not.toHaveBeenCalledWith("chat.send", expect.anything());
+  });
+
+  it.each(["/stop", "stop", "esc", "abort", "wait", "exit"])(
+    "routes active-run stop intent %s before materializing annotation context",
+    async (command) => {
+      const attachment = createBrowserAnnotationAttachment("stop", "Review the annotated page");
+      const host = makeChatHost({
+        requestHandlers: { "chat.abort": { aborted: true } },
+        chatAttachments: [attachment],
+        chatMessage: command,
+        chatRunId: "annotation-stop-run",
+      });
+
+      await handleSendChat(host);
+
+      expect(host.request).toHaveBeenCalledWith("chat.abort", {
+        runId: "annotation-stop-run",
+        sessionKey: "agent:main",
+      });
+      expect(host.request).not.toHaveBeenCalledWith("chat.send", expect.anything());
+    },
+  );
+
+  it.each(["/side", "/btw"])(
+    "opens annotated companion intent %s without sending annotation context",
+    async (command) => {
+      const attachment = createBrowserAnnotationAttachment("companion", "Review the page");
+      const openSessionCompanion = vi.fn();
+      const host = makeChatHost({
+        requestHandlers: {},
+        chatAttachments: [attachment],
+        chatMessage: `${command} explain this`,
+        openSessionCompanion,
+      });
+
+      await handleSendChat(host);
+
+      expect(openSessionCompanion).toHaveBeenCalledWith("explain this");
+      expect(host.request).not.toHaveBeenCalledWith("chat.send", expect.anything());
+    },
+  );
+
+  it("keeps annotation context on natural stop words when no run is active", async () => {
+    const attachment = createBrowserAnnotationAttachment("idle-stop", "Review the page");
+    const host = makeChatHost({
+      requestHandlers: { "chat.send": { runId: "annotation-idle-run", status: "started" } },
+      chatAttachments: [attachment],
+      chatMessage: "wait",
+    });
+
+    await handleSendChat(host);
+
+    expect(findChatSendPayload(host).message).toBe("Review the page\n\nwait");
+    expect(host.request).not.toHaveBeenCalledWith("chat.abort", expect.anything());
+  });
+
+  it("preserves annotations across remote commands until the next actual model prompt", async () => {
+    const annotation = createBrowserAnnotationAttachment("remote", "Review the annotated page");
+    const document = createStagedAttachment("remote-document");
+    const host = makeChatHost({
+      requestHandlers: { "chat.send": { runId: "annotation-command-run", status: "ok" } },
+      chatAttachments: [annotation, document],
+      chatMessage: "/status",
+    });
+
+    await handleSendChat(host);
+
+    const command = findChatSendPayload(host);
+    expect(command.message).toBe("/status");
+    expect(command.attachments).toEqual([
+      expect.objectContaining({ fileName: "brief.pdf", mimeType: "application/pdf" }),
+    ]);
+    expect(host.chatAttachments).toEqual([annotation]);
+    expect(host.chatQueue).toEqual([]);
+
+    host.request.mockClear();
+    host.chatMessage = "Explain the highlighted issue";
+    await handleSendChat(host);
+
+    const modelPrompt = findChatSendPayload(host);
+    expect(modelPrompt.message).toBe("Review the annotated page\n\nExplain the highlighted issue");
+    expect(modelPrompt.attachments).toEqual([expect.objectContaining({ mimeType: "image/png" })]);
+    expect(host.chatAttachments).toEqual([]);
+  });
+
+  it("retains annotations while forwarding an active-run approval with its ordinary file", async () => {
+    const annotation = createBrowserAnnotationAttachment("approval", "Review the annotated page");
+    const document = createStagedAttachment("approval-document");
+    const host = makeChatHost({
+      requestHandlers: { "chat.send": { runId: "approval-command-run", status: "started" } },
+      chatAttachments: [annotation, document],
+      chatMessage: "/approve approval-123 allow-once",
+      chatRunId: "active-run",
+      chatStream: "Waiting for approval...",
+    });
+
+    await handleSendChat(host);
+
+    const command = findChatSendPayload(host);
+    expect(command.message).toBe("/approve approval-123 allow-once");
+    expect(command.attachments).toEqual([
+      expect.objectContaining({ fileName: "brief.pdf", mimeType: "application/pdf" }),
+    ]);
+    expect(host.chatAttachments).toEqual([annotation]);
+    expect(host.chatMessage).toBe("");
+  });
+
+  it("restores the command draft and mixed attachments when a remote command fails", async () => {
+    const annotation = createBrowserAnnotationAttachment("failed-status", "Review the page");
+    const document = createStagedAttachment("failed-status-document");
+    const host = makeChatHost({
+      requestHandlers: { "chat.send": { runId: "failed-status-run", status: "error" } },
+      chatAttachments: [annotation, document],
+      chatMessage: "/status",
+    });
+
+    await handleSendChat(host);
+
+    expect(findChatSendPayload(host).attachments).toEqual([
+      expect.objectContaining({ fileName: "brief.pdf", mimeType: "application/pdf" }),
+    ]);
+    expect(host.chatMessage).toBe("/status");
+    expect(host.chatAttachments).toMatchObject([
+      {
+        id: annotation.id,
+        browserAnnotation: annotation.browserAnnotation,
+        dataUrl: annotation.dataUrl,
+      },
+      { id: document.id, fileName: "brief.pdf", dataUrl: attachmentDataUrl },
+    ]);
+    expect(getChatAttachmentDataUrl(host.chatAttachments[0]!)).toBe(annotation.dataUrl);
+    expect(getChatAttachmentDataUrl(host.chatAttachments[1]!)).toBe(attachmentDataUrl);
+  });
+
+  it("restores the command draft and mixed attachments when an approval fails", async () => {
+    const annotation = createBrowserAnnotationAttachment("failed-approval", "Review the page");
+    const document = createStagedAttachment("failed-approval-document");
+    const command = "/approve approval-123 allow-once";
+    const host = makeChatHost({
+      requestHandlers: { "chat.send": { runId: "failed-approval-run", status: "error" } },
+      chatAttachments: [annotation, document],
+      chatMessage: command,
+      chatRunId: "active-run",
+      chatStream: "Waiting for approval...",
+    });
+
+    await handleSendChat(host);
+
+    expect(findChatSendPayload(host).attachments).toEqual([
+      expect.objectContaining({ fileName: "brief.pdf", mimeType: "application/pdf" }),
+    ]);
+    expect(host.chatMessage).toBe(command);
+    expect(host.chatAttachments).toMatchObject([
+      {
+        id: annotation.id,
+        browserAnnotation: annotation.browserAnnotation,
+        dataUrl: annotation.dataUrl,
+      },
+      { id: document.id, fileName: "brief.pdf", dataUrl: attachmentDataUrl },
+    ]);
+    expect(getChatAttachmentDataUrl(host.chatAttachments[0]!)).toBe(annotation.dataUrl);
+    expect(getChatAttachmentDataUrl(host.chatAttachments[1]!)).toBe(attachmentDataUrl);
+  });
+
+  it("never restores over a replacement annotation that reuses the submitted attachment ID", async () => {
+    const acknowledgment = createDeferred<{ runId: string; status: "error" }>();
+    const annotation = createBrowserAnnotationAttachment("reused-annotation", "Original page");
+    const replacement = {
+      ...annotation,
+      dataUrl: "data:image/png;base64,bmV3",
+      browserAnnotation: {
+        ...annotation.browserAnnotation!,
+        modelContext: "Replacement page",
+      },
+    };
+    const host = makeChatHost({
+      requestHandlers: { "chat.send": () => acknowledgment.promise },
+      chatAttachments: [annotation],
+      chatMessage: "/approve approval-123 allow-once",
+      chatRunId: "active-run",
+      chatStream: "Waiting for approval...",
+    });
+
+    const send = handleSendChat(host);
+    await vi.waitFor(() => expect(host.request).toHaveBeenCalledOnce());
+    expect(host.chatMessage).toBe("");
+    host.chatAttachments = [replacement];
+    acknowledgment.resolve({ runId: "failed-approval-run", status: "error" });
+    await send;
+
+    expect(host.chatMessage).toBe("");
+    expect(host.chatAttachments).toEqual([replacement]);
+    expect(getChatAttachmentDataUrl(host.chatAttachments[0]!)).toBe(replacement.dataUrl);
+  });
+
+  it("never restores a failed approval over a newer composer attachment", async () => {
+    const acknowledgment = createDeferred<{ runId: string; status: "error" }>();
+    const annotation = createBrowserAnnotationAttachment("stale-approval", "Review the page");
+    const replacement = createBrowserAnnotationAttachment("replacement", "Review the newer page");
+    const host = makeChatHost({
+      requestHandlers: { "chat.send": () => acknowledgment.promise },
+      chatAttachments: [annotation],
+      chatMessage: "/approve approval-123 allow-once",
+      chatRunId: "active-run",
+      chatStream: "Waiting for approval...",
+    });
+
+    const send = handleSendChat(host);
+    await vi.waitFor(() => expect(host.request).toHaveBeenCalledOnce());
+    host.chatMessage = "Newer operator draft";
+    host.chatAttachments = [replacement];
+    acknowledgment.resolve({ runId: "failed-approval-run", status: "error" });
+    await send;
+
+    expect(host.chatMessage).toBe("Newer operator draft");
+    expect(host.chatAttachments).toEqual([replacement]);
+  });
+
+  it("materializes annotation context for unrecognized slash-prefixed input", async () => {
+    const attachment = createBrowserAnnotationAttachment("unknown", "Review the annotated page");
+    const host = makeChatHost({
+      requestHandlers: { "chat.send": { runId: "annotation-model-run", status: "started" } },
+      chatAttachments: [attachment],
+      chatMessage: "/review-this",
+    });
+
+    await handleSendChat(host);
+
+    expect(findChatSendPayload(host).message).toBe("Review the annotated page\n\n/review-this");
   });
 
   it("keeps one materialized snapshot through delayed failed delivery", async () => {
diff --git a/ui/src/pages/chat/chat-send-submit.ts b/ui/src/pages/chat/chat-send-submit.ts
index 3be87b5fd84e..e81c690e38e9 100644
--- a/ui/src/pages/chat/chat-send-submit.ts
+++ b/ui/src/pages/chat/chat-send-submit.ts
@@ -117,6 +117,7 @@ function clearSubmittedComposerState(
   host: ChatHost,
   submittedDraft: string,
   submittedAttachments: ChatAttachment[],
+  preserveBrowserAnnotations = false,
 ) {
   const attachmentsUnchanged =
     host.chatAttachments.length === submittedAttachments.length &&
@@ -129,7 +130,9 @@ function clearSubmittedComposerState(
     return {};
   }
   host.chatMessage = "";
-  host.chatAttachments = [];
+  host.chatAttachments = preserveBrowserAnnotations
+    ? host.chatAttachments.filter((attachment) => attachment.browserAnnotation)
+    : [];
   resetChatInputHistoryNavigation(host);
   return {
     previousAttachments: submittedAttachments,
@@ -225,21 +228,25 @@ export async function handleSendChat(
     return;
   }
 
-  // Materialize hidden annotation context once after inline-edit classification.
-  // Delivery and retry consume this snapshot; they must not re-read or recompose attachments.
-  const message = composeBrowserAnnotationContext(userMessage, attachmentsToSend);
+  // Commands own the raw composer text. Annotation context is model input and must not
+  // turn a recognized command into an ordinary message.
+  const message = rawParsedCommand
+    ? userMessage
+    : composeBrowserAnnotationContext(userMessage, attachmentsToSend);
+  // Slash commands may use ordinary files, but annotations belong to the next model prompt.
+  const deliveredAttachments = rawParsedCommand
+    ? attachmentsToSend.filter((attachment) => !attachment.browserAnnotation)
+    : attachmentsToSend;
 
   if (!message && !hasAttachments) {
     return;
   }
 
-  const parsedCommand = parseSlashCommand(message);
-
   {
     // Natural stop aliases require a run; explicit /stop is always available.
     if (
-      isChatStopCommand(message) &&
-      (message.trim().startsWith("/") || hasAbortableSessionRun(host))
+      isChatStopCommand(userMessage) &&
+      (userMessage.startsWith("/") || hasAbortableSessionRun(host))
     ) {
       if (host.connected && !requireChatSessionAction(host, "abort")) {
         return;
@@ -253,9 +260,9 @@ export async function handleSendChat(
     }
 
     host.chatRunError = null;
-    const parsed = parsedCommand;
-    if (/^\/(?:btw|side)(?::|\s|$)/i.test(message)) {
-      const question = extractCompanionCommandQuestion(message);
+    const parsed = rawParsedCommand;
+    if (/^\/(?:btw|side)(?::|\s|$)/i.test(userMessage)) {
+      const question = extractCompanionCommandQuestion(userMessage);
       if (!question) {
         return;
       }
@@ -320,14 +327,14 @@ export async function handleSendChat(
         }
         const cleared =
           messageOverride == null
-            ? clearSubmittedComposerState(host, previousDraft, attachmentsToSend)
+            ? clearSubmittedComposerState(host, previousDraft, attachmentsToSend, true)
             : {};
         if (messageOverride == null) {
           recordNonTranscriptInputHistory(host, userMessage);
         }
         const recoveryScope = resolveStoredChatOutboxScope(host, submittedSessionKey);
         await sendDetachedCommandMessage(host, message, {
-          attachments: hasAttachments ? attachmentsToSend : undefined,
+          attachments: deliveredAttachments.length ? deliveredAttachments : undefined,
           recovery: captureChatCommandComposerRecovery(
             host,
             recoveryScope,
@@ -500,7 +507,12 @@ export async function handleSendChat(
     }
     const cleared =
       messageOverride == null
-        ? clearSubmittedComposerState(host, previousDraft, attachmentsToSend)
+        ? clearSubmittedComposerState(
+            host,
+            previousDraft,
+            attachmentsToSend,
+            Boolean(rawParsedCommand),
+          )
         : {};
     if (messageOverride == null) {
       recordNonTranscriptInputHistory(host, userMessage);
@@ -523,7 +535,7 @@ export async function handleSendChat(
     const queued = enqueuePendingSendMessage(
       host,
       effectiveMessage,
-      hasAttachments ? attachmentsToSend : undefined,
+      deliveredAttachments.length ? deliveredAttachments : undefined,
       refreshSessions,
       submittedAtMs,
       waitingForSettings ? "waiting-model" : reconnectSafeQueuedSendState(host),

From be0bcb395d7a8cfefd8a7939cc50ab66533cd66b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 21 Aug 2026 15:58:48 -0700
Subject: [PATCH 124/124] fix(gateway): clear stale credential warnings after
 channel plugin removal (#127503)

* fix(gateway): retire removed channel credential owners

Retire stale account diagnostics only after successful channel plugin removal. Preserve independently owned credential diagnostics across snapshot replacement and rollback.

* test(gateway): cover plugin-disable owner pruning
---
 src/agents/mcp-connection-resolver.test.ts |  3 ++
 src/gateway/server-channels.test.ts        | 38 ++++++++++++++++++++++
 src/gateway/server-channels.ts             | 10 ++++++
 src/gateway/server-reload-contracts.ts     |  7 ++--
 src/gateway/server-reload-handlers.test.ts | 29 +++++++++++++++--
 src/gateway/server-reload-hot.ts           |  6 +++-
 src/gateway/server-reload-managed.ts       |  1 +
 7 files changed, 88 insertions(+), 6 deletions(-)

diff --git a/src/agents/mcp-connection-resolver.test.ts b/src/agents/mcp-connection-resolver.test.ts
index 278dd1885155..3d3440345986 100644
--- a/src/agents/mcp-connection-resolver.test.ts
+++ b/src/agents/mcp-connection-resolver.test.ts
@@ -340,6 +340,7 @@ describe("mcp connection resolver helpers", () => {
       };
       const reloadLog = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
       const requestRecoveryRestart = vi.fn(() => ({ status: "failed" as const }));
+      const pruneInactiveChannelAccountState = vi.fn();
       const nextConfig: OpenClawConfig = {
         plugins: {
           entries: {
@@ -365,6 +366,7 @@ describe("mcp connection resolver helpers", () => {
         },
         async startChannel() {},
         async stopChannel() {},
+        pruneInactiveChannelAccountState,
         async reloadPlugins({ beforeReplace, commitRuntime }) {
           await beforeReplace(new Set());
           await commitRuntime();
@@ -392,6 +394,7 @@ describe("mcp connection resolver helpers", () => {
       });
       expect(refreshContextWindowCache).toHaveBeenCalledWith(nextConfig);
       expect(requestRecoveryRestart).not.toHaveBeenCalled();
+      expect(pruneInactiveChannelAccountState).toHaveBeenCalledExactlyOnceWith(new Set());
       expect(isPluginRegistryRetired(previous.registry)).toBe(true);
       expect(peekSessionMcpRuntime({ sessionId })).toBeUndefined();
 
diff --git a/src/gateway/server-channels.test.ts b/src/gateway/server-channels.test.ts
index ae23251e738b..b60e852d2251 100644
--- a/src/gateway/server-channels.test.ts
+++ b/src/gateway/server-channels.test.ts
@@ -3087,6 +3087,44 @@ describe("server-channels auto restart", () => {
     ]);
   });
 
+  it("prunes only credential owners and account state for inactive channel plugins", async () => {
+    installTestRegistry(
+      ...(["discord", "slack"] as const).map((channelId) =>
+        createTestPlugin({
+          id: channelId,
+          listAccountIds: () => ["Ops Team"],
+          startAccount: async () => {},
+          resolveAccount: (_cfg, accountId) => ({
+            enabled: true,
+            configured: true,
+            credentialDiagnostics: [
+              {
+                code: "CREDENTIAL_FILE_UNAVAILABLE" as const,
+                path: `channels.${channelId}.accounts.${accountId}.tokenFile`,
+                reason: "not-found",
+              },
+            ],
+          }),
+        }),
+      ),
+    );
+    const manager = createManager({ channelIds: ["discord", "slack"] });
+
+    await manager.startChannels();
+    expect(listActiveDegradedSecretOwners().map((owner) => owner.ownerId)).toEqual([
+      "discord:ops-team",
+      "slack:ops-team",
+    ]);
+
+    manager.pruneInactiveChannelAccountState(new Set(["slack"]));
+
+    expect(listActiveDegradedSecretOwners().map((owner) => owner.ownerId)).toEqual([
+      "slack:ops-team",
+    ]);
+    expect(manager.resolveRuntimeAccountId("discord", "ops-team")).toBeUndefined();
+    expect(manager.resolveRuntimeAccountId("slack", "ops-team")).toBe("Ops Team");
+  });
+
   it("resolves only an unambiguous authoritative runtime account for a normalized owner", async () => {
     let accountIds = ["Ops Team"];
     installTestRegistry(
diff --git a/src/gateway/server-channels.ts b/src/gateway/server-channels.ts
index f759edfa1096..874f8a878ee4 100644
--- a/src/gateway/server-channels.ts
+++ b/src/gateway/server-channels.ts
@@ -284,6 +284,7 @@ export type ChannelManager = {
 
 // Channel docking: lifecycle hooks (`plugin.gateway`) flow through this manager.
 export function createChannelManager(opts: ChannelManagerOptions): ChannelManager & {
+  pruneInactiveChannelAccountState: (activeChannelIds: ReadonlySet<ChannelId>) => void;
   resolveRuntimeAccountId: (channelId: ChannelId, accountId: string) => string | undefined;
 } {
   const {
@@ -500,6 +501,14 @@ export function createChannelManager(opts: ChannelManagerOptions): ChannelManage
     }
   };
 
+  const pruneInactiveChannelAccountState = (activeChannelIds: ReadonlySet<ChannelId>): void => {
+    for (const [channelId, store] of channelStores) {
+      if (!activeChannelIds.has(channelId)) {
+        evictStaleChannelAccountState(channelId, store, []);
+      }
+    }
+  };
+
   const startChannelProcessOwned = async (
     channelId: ChannelId,
     accountId?: string,
@@ -1420,6 +1429,7 @@ export function createChannelManager(opts: ChannelManagerOptions): ChannelManage
     startChannels,
     startChannel,
     stopChannel,
+    pruneInactiveChannelAccountState,
     setAutostartSuppression: (suppression) => {
       autostartSuppression = suppression;
     },
diff --git a/src/gateway/server-reload-contracts.ts b/src/gateway/server-reload-contracts.ts
index 02ea1d7e3685..f2ca0639e127 100644
--- a/src/gateway/server-reload-contracts.ts
+++ b/src/gateway/server-reload-contracts.ts
@@ -151,6 +151,7 @@ export type GatewayReloadHandlerParams = {
   getPluginMetadataSnapshot?: () => PluginMetadataSnapshot | undefined;
   startChannel: GatewayChannelManager["startChannel"];
   stopChannel: GatewayChannelManager["stopChannel"];
+  pruneInactiveChannelAccountState: (activeChannelIds: ReadonlySet<ChannelKind>) => void;
   getChannelAutostartSuppression?: GatewayChannelManager["getAutostartSuppression"];
   stopPostReadySidecars?: () => Promise<void> | void;
   reloadPlugins: (params: {
@@ -187,7 +188,7 @@ export type GatewayReloadHandlerParams = {
 
 export type ManagedGatewayConfigReloaderParams = Omit<
   GatewayReloadHandlerParams,
-  "assertRestartReady" | "createHealthMonitor" | "logReload"
+  "assertRestartReady" | "createHealthMonitor" | "logReload" | "pruneInactiveChannelAccountState"
 > & {
   configRevisionProjector: import("./config-revision-token.js").GatewayConfigRevisionProjector;
   minimalTestGateway: boolean;
@@ -204,7 +205,9 @@ export type ManagedGatewayConfigReloaderParams = Omit<
   promoteSnapshot: typeof import("../config/config.js").promoteConfigSnapshotToLastKnownGood;
   subscribeToWrites: typeof import("../config/config.js").registerConfigWriteListener;
   logReload: GatewayReloadLog & { error: (msg: string) => void };
-  channelManager: GatewayChannelManager;
+  channelManager: GatewayChannelManager & {
+    pruneInactiveChannelAccountState: GatewayReloadHandlerParams["pruneInactiveChannelAccountState"];
+  };
   activateRuntimeSecrets: ActivateRuntimeSecrets;
   /** Applies one immutable effective config/compare snapshot before reload planning. */
   prepareConfigCandidate?: (params: {
diff --git a/src/gateway/server-reload-handlers.test.ts b/src/gateway/server-reload-handlers.test.ts
index 63a6df105fb8..cf68423a7d5d 100644
--- a/src/gateway/server-reload-handlers.test.ts
+++ b/src/gateway/server-reload-handlers.test.ts
@@ -133,6 +133,7 @@ function createGatewayReloadHandlers(
     setState: vi.fn(),
     startChannel: vi.fn(async () => {}),
     stopChannel: vi.fn(async () => {}),
+    pruneInactiveChannelAccountState: vi.fn(),
     stopPostReadySidecars: vi.fn(),
     reloadPlugins: vi.fn(async () => makePluginReloadResult()),
     logHooks: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
@@ -196,7 +197,7 @@ function startManagedGatewayConfigReloader(params: ManagedReloaderTestParams) {
     logChannels: { info: vi.fn(), error: vi.fn() },
     logCron: { error: vi.fn() },
     logReload: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
-    channelManager: {} as never,
+    channelManager: { pruneInactiveChannelAccountState: vi.fn() } as never,
     activateRuntimeSecrets: vi.fn(async (config: OpenClawConfig) =>
       makePreparedSecretsSnapshot(config),
     ) as never,
@@ -611,6 +612,7 @@ function createReloadHandlersForTest(
   channels?: {
     start: ReloadHandlerParams["startChannel"];
     stop: ReloadHandlerParams["stopChannel"];
+    pruneInactiveChannelAccountState?: ReloadHandlerParams["pruneInactiveChannelAccountState"];
   },
   reloadPlugins?: Parameters<typeof createGatewayReloadHandlers>[0]["reloadPlugins"],
   stopPostReadySidecars = vi.fn(),
@@ -648,6 +650,9 @@ function createReloadHandlersForTest(
     setState,
     startChannel: channels?.start ?? vi.fn(async () => {}),
     stopChannel: channels?.stop ?? vi.fn(async () => {}),
+    ...(channels?.pruneInactiveChannelAccountState
+      ? { pruneInactiveChannelAccountState: channels.pruneInactiveChannelAccountState }
+      : {}),
     ...(reloadPlugins ? { reloadPlugins } : {}),
     getChannelAutostartSuppression: options?.getChannelAutostartSuppression,
     stopPostReadySidecars,
@@ -5583,6 +5588,7 @@ describe("gateway plugin hot reload handlers", () => {
 
   it("restarts pre-stopped channel targets when runtime publication fails", async () => {
     const events: string[] = [];
+    const pruneInactiveChannelAccountState = vi.fn();
     const publish = vi.fn(async () => {
       throw new Error("publication failed");
     });
@@ -5611,6 +5617,7 @@ describe("gateway plugin hot reload handlers", () => {
         start: vi.fn(async (channel, accountId) => {
           events.push(`start:${channel}:${accountId ?? "all"}`);
         }),
+        pruneInactiveChannelAccountState,
       },
       reloadPlugins,
     );
@@ -5629,11 +5636,13 @@ describe("gateway plugin hot reload handlers", () => {
       "start:slack:catalog-account",
       "start:discord:all",
     ]);
+    expect(pruneInactiveChannelAccountState).not.toHaveBeenCalled();
     expect(handlers.setState).not.toHaveBeenCalled();
   });
 
   it("restarts pre-stopped account targets when plugin replacement is cancelled", async () => {
     const events: string[] = [];
+    const pruneInactiveChannelAccountState = vi.fn();
     const reloadPlugins = vi.fn(
       async (params: {
         beforeReplace: (
@@ -5656,6 +5665,7 @@ describe("gateway plugin hot reload handlers", () => {
         start: vi.fn(async (channel, accountId) => {
           events.push(`start:${channel}:${accountId ?? "all"}`);
         }),
+        pruneInactiveChannelAccountState,
       },
       reloadPlugins,
     );
@@ -5665,6 +5675,7 @@ describe("gateway plugin hot reload handlers", () => {
     ).rejects.toThrow("config hot reload cancelled by config supersession or in-process restart");
 
     expect(events).toEqual(["stop:discord:catalog-account", "start:discord:catalog-account"]);
+    expect(pruneInactiveChannelAccountState).not.toHaveBeenCalled();
     expect(handlers.setState).not.toHaveBeenCalled();
   });
 
@@ -5675,6 +5686,7 @@ describe("gateway plugin hot reload handlers", () => {
     const logChannels = { info: vi.fn(), error: vi.fn() };
     const events: string[] = [];
     const startRootCounts: number[] = [];
+    const pruneInactiveChannelAccountState = vi.fn();
     const startChannel = vi.fn(async (channel: ChannelKind) => {
       events.push(`start:${channel}`);
       startRootCounts.push(getActiveGatewayRootWorkCount({ excludeCurrent: true }));
@@ -5700,6 +5712,7 @@ describe("gateway plugin hot reload handlers", () => {
       setState,
       startChannel,
       stopChannel,
+      pruneInactiveChannelAccountState,
       reloadPlugins,
       logChannels,
     });
@@ -5734,6 +5747,7 @@ describe("gateway plugin hot reload handlers", () => {
     expect(startChannel).toHaveBeenCalledWith("telegram");
     expect(startChannel).toHaveBeenCalledWith("discord");
     expect(startRootCounts).toEqual([1, 1]);
+    expect(pruneInactiveChannelAccountState).not.toHaveBeenCalled();
     expect(setState).not.toHaveBeenCalled();
   });
 
@@ -5743,6 +5757,10 @@ describe("gateway plugin hot reload handlers", () => {
     const setState = vi.fn();
     const startChannel = vi.fn(async () => {});
     const events: string[] = [];
+    const activeChannels = new Set<ChannelKind>(["slack"]);
+    const pruneInactiveChannelAccountState = vi.fn(() => {
+      events.push("prune");
+    });
     const stopChannel = vi.fn(async () => {
       events.push("stop");
     });
@@ -5753,7 +5771,7 @@ describe("gateway plugin hot reload handlers", () => {
         events.push("reload:start");
         await params.beforeReplace(new Set(["discord"]));
         events.push("registry:replace");
-        return makePluginReloadResult();
+        return makePluginReloadResult({ activeChannels });
       },
     );
     const { applyHotReload } = createGatewayReloadHandlers({
@@ -5761,6 +5779,7 @@ describe("gateway plugin hot reload handlers", () => {
       setState,
       startChannel,
       stopChannel,
+      pruneInactiveChannelAccountState,
       reloadPlugins,
     });
     const sourceConfig: OpenClawConfig = {
@@ -5798,7 +5817,8 @@ describe("gateway plugin hot reload handlers", () => {
     expect(reloadParamsRecord?.changedPaths).toEqual(["plugins.enabled"]);
     expect(stopChannel).toHaveBeenCalledWith("discord", undefined, { manual: false });
     expect(startChannel).not.toHaveBeenCalled();
-    expect(events).toEqual(["reload:start", "stop", "registry:replace"]);
+    expect(pruneInactiveChannelAccountState).toHaveBeenCalledExactlyOnceWith(activeChannels);
+    expect(events).toEqual(["reload:start", "stop", "registry:replace", "prune"]);
     expect(setState).toHaveBeenCalledTimes(1);
   });
 
@@ -6163,6 +6183,7 @@ describe("deferred channel reload abort generation", () => {
       start: vi.fn(async () => {}),
       stop: vi.fn(async () => {}),
     };
+    const pruneInactiveChannelAccountState = vi.fn();
     let receivedIsAborted = false;
     let reloadWasCancelled = false;
     const reloadPlugins = vi.fn(
@@ -6185,6 +6206,7 @@ describe("deferred channel reload abort generation", () => {
     const { applyHotReload } = createGatewayReloadHandlers({
       startChannel: channels.start,
       stopChannel: channels.stop,
+      pruneInactiveChannelAccountState,
       reloadPlugins,
       logChannels,
     });
@@ -6217,6 +6239,7 @@ describe("deferred channel reload abort generation", () => {
       // No channel should be started — cancelledByRestart = pluginReloadAborted = true
       expect(channels.start).not.toHaveBeenCalled();
       expect(channels.stop).not.toHaveBeenCalled();
+      expect(pruneInactiveChannelAccountState).not.toHaveBeenCalled();
     } finally {
       vi.useRealTimers();
       hoisted.activeTaskBlockers.length = 0;
diff --git a/src/gateway/server-reload-hot.ts b/src/gateway/server-reload-hot.ts
index b3d0283750a8..a12022f38e2d 100644
--- a/src/gateway/server-reload-hot.ts
+++ b/src/gateway/server-reload-hot.ts
@@ -550,12 +550,16 @@ export function createGatewayReloadHandlers(params: GatewayReloadHandlerParams)
         }
         // beforeReplace may have set pluginReloadAborted inside reloadPlugins;
         // skip metadata/runtime updates when the reload was cancelled mid-flight.
-        if (!pluginReloadAborted) {
+        if (!pluginReloadAborted && !isLifecycleReloadAborted()) {
           for (const channel of pluginReloadResult.restartChannels) {
             channelsToRestart.add(channel);
           }
           activePluginChannelsAfterReload = pluginReloadResult.activeChannels;
+          // Only a successfully published replacement can authoritatively retire channel owners.
+          params.pruneInactiveChannelAccountState(activePluginChannelsAfterReload);
           resetPreparedModelRuntimeStateForHotReload();
+        } else {
+          pluginReloadAborted = true;
         }
       }
     }
diff --git a/src/gateway/server-reload-managed.ts b/src/gateway/server-reload-managed.ts
index 7909ce59a2bb..2d5f6f785571 100644
--- a/src/gateway/server-reload-managed.ts
+++ b/src/gateway/server-reload-managed.ts
@@ -142,6 +142,7 @@ export function startManagedGatewayConfigReloader(
     getPluginMetadataSnapshot: params.getPluginMetadataSnapshot,
     startChannel: params.startChannel,
     stopChannel: params.stopChannel,
+    pruneInactiveChannelAccountState: params.channelManager.pruneInactiveChannelAccountState,
     getChannelAutostartSuppression: params.getChannelAutostartSuppression,
     stopPostReadySidecars: params.stopPostReadySidecars,
     reloadPlugins: params.reloadPlugins,