test(plugin-sdk): refresh callable export budget expectation

normalizeRoleList in src/shared/device-pairing-access.ts called .trim() on every roles[] entry and the singular role without a typeof === "string" guard, so a malformed/legacy on-disk pairing record (roles/role loaded via blind-cast JSON in coercePairingStateRecord) threw "TypeError: role.trim is not a function" and crashed resolvePendingDeviceApprovalState -- and thus `openclaw devices list`, which calls it per pending request with no try/catch.

Route each item through the shared non-string-safe normalizer normalizeUniqueSingleOrTrimmedStringList, mirroring the #90654/#92178 fix that already guarded the sibling mergeRoles/mergeScopes (src/infra/device-pairing.ts) and the in-file scopes path (normalizeDeviceAuthScopes). Non-string entries are dropped; valid roles are still trimmed, deduped, and sorted. Net -10 LOC.

Co-authored-by: ly-wang19 <ly-wang19@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.agents/skills/openclaw-pr-maintainer/scripts/github-activity.sh

@@ -4,6 +4,14 @@ set -euo pipefail
 repo="openclaw/openclaw"
 months="12"
 include_global="0"
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(git -C "$script_dir/../../../.." rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$repo_root" ]; then
+  repo_root="$(cd "$script_dir/../../../.." && pwd)"
+fi
+
+# shellcheck disable=SC1091
+source "$repo_root/scripts/lib/plain-gh.sh"
 
 usage() {
   printf 'Usage: %s [--repo owner/repo] [--months N] [--global] <github-login> [login...]\n' "$0"
@@ -18,6 +26,10 @@ need() {
   command -v "$1" >/dev/null 2>&1 || die "missing required command: $1"
 }
 
+gh() {
+  gh_plain "$@"
+}
+
 date_utc_relative_months() {
   local count="$1"
   if date -u -v-"${count}"m +%Y-%m-%dT00:00:00Z >/dev/null 2>&1; then
@@ -131,7 +143,8 @@ done
   exit 2
 }
 
-need gh
+OPENCLAW_GH_BIN="$(resolve_plain_gh_bin)" || die "missing required command: gh"
+export OPENCLAW_GH_BIN
 need jq
 
 since_ts=$(date_utc_relative_months "$months")

.agents/skills/openclaw-secret-scanning-maintainer/scripts/secret-scanning.mjs

@@ -4,12 +4,12 @@
  * Usage: node secret-scanning.mjs <command> [options]
  */
 
-import { spawnSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { spawnPlainGh } from "../../../../scripts/lib/plain-gh.mjs";
 
 const REPO = "openclaw/openclaw";
 const REPO_URL = `https://github.com/${REPO}`;
@@ -29,7 +29,7 @@ function tmpFile(purpose) {
 }
 
 function gh(args, { json = true, allowFailure = false } = {}) {
-  const proc = spawnSync("gh", args, { encoding: "utf8", maxBuffer: 10 * 1024 * 1024 });
+  const proc = spawnPlainGh(args, { encoding: "utf8", maxBuffer: 10 * 1024 * 1024 });
   if (proc.status !== 0 && !allowFailure) {
     fail(`gh ${args.slice(0, 3).join(" ")} failed:\n${(proc.stderr || proc.stdout || "").trim()}`);
   }

.agents/skills/release-openclaw-ci/scripts/release-ci-summary.mjs

@@ -5,6 +5,7 @@
  */
 import { execFileSync } from "node:child_process";
 import process from "node:process";
+import { plainGhEnv, resolvePlainGhBin } from "../../../../scripts/lib/plain-gh.mjs";
 
 const runId = process.argv[2];
 const repo = process.env.OPENCLAW_RELEASE_REPO || "openclaw/openclaw";
@@ -15,8 +16,9 @@ if (!runId) {
 }
 
 function gh(args) {
-  return execFileSync("gh", args, {
+  return execFileSync(resolvePlainGhBin(), args, {
     encoding: "utf8",
+    env: plainGhEnv(),
     stdio: ["ignore", "pipe", "pipe"],
   });
 }
@@ -32,14 +34,15 @@ function githubRestJson(pathSuffix) {
       "-lc",
       [
         "set -euo pipefail",
-        'token="$(gh auth token)"',
+        'token="$("$OPENCLAW_PLAIN_GH_BIN" auth token)"',
         'curl -fsS -H "Authorization: Bearer ${token}" -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" "${OPENCLAW_GITHUB_REST_URL}"',
       ].join("\n"),
     ],
     {
       encoding: "utf8",
       env: {
-        ...process.env,
+        ...plainGhEnv(),
+        OPENCLAW_PLAIN_GH_BIN: resolvePlainGhBin(),
         OPENCLAW_GITHUB_REST_URL: `https://api.github.com/repos/${repo}/${pathSuffix}`,
       },
       maxBuffer: 16 * 1024 * 1024,

.github/codeql/codeql-memory-runtime-boundary-critical-quality.yml

@@ -22,7 +22,7 @@ paths:
   - src/plugins/memory-*.ts
   - src/gateway/server-startup-memory.ts
   - src/commands/doctor-memory-search.ts
-  - src/commands/doctor-cron-dreaming-payload-migration.ts
+  - src/commands/doctor/cron/dreaming-payload-migration.ts
 
 paths-ignore:
   - "**/node_modules"

.github/codeql/codeql-plugin-boundary-critical-quality.yml

@@ -19,7 +19,6 @@ paths:
   - src/plugins/bundled-compat.ts
   - src/plugins/bundled-dir.ts
   - src/plugins/bundled-plugin-metadata.ts
-  - src/plugins/bundled-public-surface-runtime-root.ts
   - src/plugins/plugin-sdk-dist-alias.ts
   - src/plugins/captured-registration.ts
   - src/plugins/config-activation-shared.ts
@@ -46,7 +45,6 @@ paths:
   - src/plugins/runtime-state.ts
   - src/plugins/runtime.ts
   - src/plugins/sdk-alias.ts
-  - src/plugins/source-loader.ts
   - src/plugins/types.ts
   - src/plugins/validation-diagnostics.ts
   - src/plugins/web-provider-public-artifacts*.ts

.github/codeql/codeql-plugin-trust-boundary-critical-security.yml

@@ -51,7 +51,6 @@ paths:
   - src/plugins/runtime
   - src/plugins/runtime-state.ts
   - src/plugins/runtime.ts
-  - src/plugins/source-loader.ts
   - src/plugins/update.ts
   - src/plugins/validation-diagnostics.ts
   - src/plugin-sdk/*entry*.ts

.github/labeler.yml

@@ -41,12 +41,6 @@
       - any-glob-to-any-file:
           - "extensions/google-meet/**"
           - "docs/plugins/google-meet.md"
-"plugin: meeting-notes":
-  - changed-files:
-      - any-glob-to-any-file:
-          - "extensions/meeting-notes/**"
-          - "docs/plugins/meeting-notes.md"
-          - "src/meeting-notes/**"
 "plugin: workboard":
   - changed-files:
       - any-glob-to-any-file:
@@ -109,6 +103,11 @@
       - any-glob-to-any-file:
           - "extensions/qqbot/**"
           - "docs/channels/qqbot.md"
+"channel: raft":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/raft/**"
+          - "docs/channels/raft.md"
 "channel: qa-channel":
   - changed-files:
       - any-glob-to-any-file:
@@ -252,12 +251,12 @@
           - "src/agents/sandbox*.ts"
           - "src/commands/sandbox*.ts"
           - "src/cli/sandbox-cli.ts"
-          - "src/docker-setup.test.ts"
+          - "src/docker-setup.e2e.test.ts"
           - "src/config/**/*sandbox*"
           - "docs/cli/sandbox.md"
           - "docs/gateway/sandbox*.md"
           - "docs/install/docker.md"
-          - "docs/multi-agent-sandbox-tools.md"
+          - "docs/tools/multi-agent-sandbox-tools.md"
 
 "agents":
   - changed-files:
@@ -270,7 +269,7 @@
           - ".github/workflows/opengrep-*.yml"
           - ".semgrepignore"
           - "docs/cli/security.md"
-          - "docs/gateway/security.md"
+          - "docs/gateway/security/**"
           - "security/**"
 
 "extensions: admin-http-rpc":

.github/workflows/ci.yml

@@ -41,11 +41,32 @@ env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
 
 jobs:
+  # Keep the canonical main queue quiet long enough for a follow-up push to
+  # cancel this run before it registers the Blacksmith matrix.
+  runner-admission:
+    permissions:
+      contents: read
+    runs-on: ubuntu-24.04
+    timeout-minutes: 3
+    env:
+      OPENCLAW_MAIN_CI_DEBOUNCE_SECONDS: "90"
+    steps:
+      - name: Debounce canonical main pushes
+        if: github.event_name == 'push' && github.repository == 'openclaw/openclaw' && github.ref == 'refs/heads/main'
+        run: |
+          set -euo pipefail
+          echo "Waiting ${OPENCLAW_MAIN_CI_DEBOUNCE_SECONDS}s for a superseding main push before Blacksmith admission"
+          sleep "${OPENCLAW_MAIN_CI_DEBOUNCE_SECONDS}"
+      - name: Admit non-main CI runs immediately
+        if: github.event_name != 'push' || github.repository != 'openclaw/openclaw' || github.ref != 'refs/heads/main'
+        run: echo "No canonical main debounce required"
+
   # Preflight: establish routing truth and job matrices once, then let real
   # work fan out from a single source of truth.
   preflight:
     permissions:
       contents: read
+    needs: [runner-admission]
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ${{ github.event_name == 'workflow_dispatch' && 'ubuntu-24.04' || (github.repository == 'openclaw/openclaw' && 'blacksmith-4vcpu-ubuntu-2404' || 'ubuntu-24.04') }}
     timeout-minutes: 20
@@ -197,7 +218,7 @@ jobs:
           node --input-type=module <<'EOF'
           import { appendFileSync } from "node:fs";
           import {
-            createNodeTestShards,
+            createNodeTestShardBundles,
           } from "./scripts/lib/ci-node-test-plan.mjs";
           import {
             createChannelContractTestShards,
@@ -272,18 +293,22 @@ jobs:
             }
           }
 
+          const compactPullRequest = isCanonicalRepository && eventName === "pull_request";
           const nodeTestShards = runNodeFull
-            ? createNodeTestShards({
+            ? createNodeTestShardBundles({
                 includeReleaseOnlyPluginShards: false,
+                compact: compactPullRequest,
               }).map((shard) => ({
                 check_name: shard.checkName,
                 runtime: "node",
                 task: "test-shard",
                 shard_name: shard.shardName,
+                groups: shard.groups,
                 configs: shard.configs,
                 includePatterns: shard.includePatterns,
                 requires_dist: shard.requiresDist,
                 runner: shard.runner,
+                timeout_minutes: shard.timeoutMinutes,
               }))
             : [];
           const nodeTestNonDistShards = nodeTestShards.filter((shard) => !shard.requires_dist);
@@ -320,7 +345,14 @@ jobs:
             run_checks_windows: runWindows,
             checks_windows_matrix: createMatrix(
               runWindows
-                ? [{ check_name: "checks-windows-node-test", runtime: "node", task: "test" }]
+                ? [
+                    {
+                      check_name: "checks-windows-node-test",
+                      runtime: "node",
+                      task: "test",
+                      runner: "blacksmith-8vcpu-windows-2025",
+                    },
+                  ]
                 : [],
             ),
             run_macos_node: runMacos,
@@ -354,6 +386,7 @@ jobs:
   security-fast:
     permissions:
       contents: read
+    needs: [runner-admission]
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ${{ github.event_name == 'workflow_dispatch' && 'ubuntu-24.04' || (github.repository == 'openclaw/openclaw' && 'blacksmith-4vcpu-ubuntu-2404' || 'ubuntu-24.04') }}
     timeout-minutes: 20
@@ -558,7 +591,7 @@ jobs:
       contents: read
     needs: [preflight]
     if: needs.preflight.outputs.run_build_artifacts == 'true'
-    runs-on: ${{ github.event_name == 'workflow_dispatch' && 'ubuntu-24.04' || (github.repository == 'openclaw/openclaw' && 'blacksmith-32vcpu-ubuntu-2404' || 'ubuntu-24.04') }}
+    runs-on: ${{ github.event_name == 'workflow_dispatch' && 'ubuntu-24.04' || (github.repository == 'openclaw/openclaw' && 'blacksmith-16vcpu-ubuntu-2404' || 'ubuntu-24.04') }}
     timeout-minutes: 20
     outputs:
       channels-result: ${{ steps.built_artifact_checks.outputs['channels-result'] }}
@@ -819,6 +852,7 @@ jobs:
     timeout-minutes: 60
     strategy:
       fail-fast: false
+      max-parallel: 8
       matrix: ${{ fromJson(needs.preflight.outputs.checks_fast_core_matrix) }}
     steps:
       - name: Checkout
@@ -908,6 +942,7 @@ jobs:
     timeout-minutes: 60
     strategy:
       fail-fast: false
+      max-parallel: 8
       matrix: ${{ fromJson(needs.preflight.outputs.plugin_contracts_matrix) }}
     steps:
       - name: Checkout
@@ -988,6 +1023,7 @@ jobs:
     timeout-minutes: 60
     strategy:
       fail-fast: false
+      max-parallel: 8
       matrix: ${{ fromJson(needs.preflight.outputs.channel_contracts_matrix) }}
     steps:
       - name: Checkout
@@ -1136,10 +1172,11 @@ jobs:
     name: ${{ matrix.check_name }}
     needs: [preflight]
     if: needs.preflight.outputs.run_checks_node_core_nondist == 'true'
-    runs-on: ${{ github.event_name == 'workflow_dispatch' && 'ubuntu-24.04' || (github.repository == 'openclaw/openclaw' && (matrix.runner || 'blacksmith-8vcpu-ubuntu-2404') || 'ubuntu-24.04') }}
-    timeout-minutes: 60
+    runs-on: ${{ github.event_name == 'workflow_dispatch' && 'ubuntu-24.04' || (github.repository == 'openclaw/openclaw' && (matrix.runner || 'blacksmith-4vcpu-ubuntu-2404') || 'ubuntu-24.04') }}
+    timeout-minutes: ${{ matrix.timeout_minutes || 60 }}
     strategy:
       fail-fast: false
+      max-parallel: 12
       matrix: ${{ fromJson(needs.preflight.outputs.checks_node_core_nondist_matrix) }}
     steps:
       - name: Checkout
@@ -1198,6 +1235,7 @@ jobs:
       - name: Run Node test shard
         env:
           NODE_OPTIONS: --max-old-space-size=8192
+          OPENCLAW_NODE_TEST_GROUPS_JSON: ${{ toJson(matrix.groups || null) }}
           OPENCLAW_NODE_TEST_CONFIGS_JSON: ${{ toJson(matrix.configs) }}
           OPENCLAW_NODE_TEST_INCLUDE_PATTERNS_JSON: ${{ toJson(matrix.includePatterns) }}
           OPENCLAW_VITEST_SHARD_NAME: ${{ matrix.shard_name }}
@@ -1212,28 +1250,47 @@ jobs:
           import { writeFileSync } from "node:fs";
           import { join } from "node:path";
 
-          const configs = JSON.parse(process.env.OPENCLAW_NODE_TEST_CONFIGS_JSON ?? "[]");
-          if (!Array.isArray(configs) || configs.length === 0) {
-            console.error("Missing node test shard configs");
-            process.exit(1);
-          }
-          const includePatterns = JSON.parse(process.env.OPENCLAW_NODE_TEST_INCLUDE_PATTERNS_JSON ?? "null");
-          const childEnv = { ...process.env };
-          if (Array.isArray(includePatterns) && includePatterns.length > 0) {
-            const includeFile = join(
-              process.env.RUNNER_TEMP ?? ".",
-              `node-test-include-${process.env.GITHUB_JOB ?? "local"}-${Date.now()}.json`,
+          const groups = JSON.parse(process.env.OPENCLAW_NODE_TEST_GROUPS_JSON ?? "null");
+          const plans = Array.isArray(groups) && groups.length > 0
+            ? groups
+            : [{
+                configs: JSON.parse(process.env.OPENCLAW_NODE_TEST_CONFIGS_JSON ?? "[]"),
+                includePatterns: JSON.parse(
+                  process.env.OPENCLAW_NODE_TEST_INCLUDE_PATTERNS_JSON ?? "null",
+                ),
+                shard_name: process.env.OPENCLAW_VITEST_SHARD_NAME,
+              }];
+          for (const plan of plans) {
+            const configs = plan.configs;
+            if (!Array.isArray(configs) || configs.length === 0) {
+              console.error("Missing node test shard configs");
+              process.exit(1);
+            }
+            const childEnv = {
+              ...process.env,
+              ...(plan.shard_name ? { OPENCLAW_VITEST_SHARD_NAME: plan.shard_name } : {}),
+            };
+            if (Array.isArray(plan.includePatterns) && plan.includePatterns.length > 0) {
+              const includeFile = join(
+                process.env.RUNNER_TEMP ?? ".",
+                `node-test-include-${process.env.GITHUB_JOB ?? "local"}-${Date.now()}.json`,
+              );
+              writeFileSync(includeFile, JSON.stringify(plan.includePatterns), "utf8");
+              childEnv.OPENCLAW_VITEST_INCLUDE_FILE = includeFile;
+            } else {
+              delete childEnv.OPENCLAW_VITEST_INCLUDE_FILE;
+            }
+            const result = spawnSync(
+              "pnpm",
+              ["exec", "node", "scripts/test-projects.mjs", ...configs],
+              {
+                env: childEnv,
+                stdio: "inherit",
+              },
             );
-            writeFileSync(includeFile, JSON.stringify(includePatterns), "utf8");
-            childEnv.OPENCLAW_VITEST_INCLUDE_FILE = includeFile;
-          }
-
-          const result = spawnSync("pnpm", ["exec", "node", "scripts/test-projects.mjs", ...configs], {
-            env: childEnv,
-            stdio: "inherit",
-          });
-          if ((result.status ?? 1) !== 0) {
-            process.exit(result.status ?? 1);
+            if ((result.status ?? 1) !== 0) {
+              process.exit(result.status ?? 1);
+            }
           }
           EOF
 
@@ -1248,6 +1305,7 @@ jobs:
     timeout-minutes: 20
     strategy:
       fail-fast: false
+      max-parallel: 8
       matrix:
         include:
           - check_name: check-guards
@@ -1264,7 +1322,7 @@ jobs:
             runner: blacksmith-16vcpu-ubuntu-2404
           - check_name: check-dependencies
             task: dependencies
-            runner: blacksmith-8vcpu-ubuntu-2404
+            runner: blacksmith-4vcpu-ubuntu-2404
           - check_name: check-test-types
             task: test-types
             runner: blacksmith-4vcpu-ubuntu-2404
@@ -1385,30 +1443,39 @@ jobs:
     name: ${{ matrix.check_name }}
     needs: [preflight]
     if: ${{ !cancelled() && always() && needs.preflight.outputs.run_check_additional == 'true' }}
-    runs-on: ${{ github.event_name == 'workflow_dispatch' && 'ubuntu-24.04' || (github.repository == 'openclaw/openclaw' && 'blacksmith-8vcpu-ubuntu-2404' || 'ubuntu-24.04') }}
+    runs-on: ${{ github.event_name == 'workflow_dispatch' && 'ubuntu-24.04' || (github.repository == 'openclaw/openclaw' && (matrix.runner || 'blacksmith-4vcpu-ubuntu-2404') || 'ubuntu-24.04') }}
     timeout-minutes: 20
     strategy:
       fail-fast: false
+      max-parallel: 8
       matrix:
         include:
           - check_name: check-additional-boundaries-a
             group: boundaries
             boundary_shard: 1/4
+            runner: blacksmith-8vcpu-ubuntu-2404
           - check_name: check-additional-boundaries-bcd
             group: boundaries
             boundary_shard: 2/4,3/4,4/4
+            runner: blacksmith-8vcpu-ubuntu-2404
           - check_name: check-session-accessor-boundary
             group: session-accessor-boundary
+            runner: blacksmith-4vcpu-ubuntu-2404
           - check_name: check-session-transcript-reader-boundary
             group: session-transcript-reader-boundary
+            runner: blacksmith-4vcpu-ubuntu-2404
           - check_name: check-additional-extension-channels
             group: extension-channels
+            runner: blacksmith-8vcpu-ubuntu-2404
           - check_name: check-additional-extension-bundled
             group: extension-bundled
+            runner: blacksmith-8vcpu-ubuntu-2404
           - check_name: check-additional-extension-package-boundary
             group: extension-package-boundary
+            runner: blacksmith-8vcpu-ubuntu-2404
           - check_name: check-additional-runtime-topology-architecture
             group: runtime-topology-architecture
+            runner: blacksmith-4vcpu-ubuntu-2404
     steps:
       - name: Checkout
         shell: bash
@@ -1751,7 +1818,7 @@ jobs:
     name: ${{ matrix.check_name }}
     needs: [preflight]
     if: needs.preflight.outputs.run_checks_windows == 'true'
-    runs-on: ${{ github.event_name == 'workflow_dispatch' && 'windows-2025' || (github.repository == 'openclaw/openclaw' && 'blacksmith-16vcpu-windows-2025' || 'windows-2025') }}
+    runs-on: ${{ github.event_name == 'workflow_dispatch' && 'windows-2025' || (github.repository == 'openclaw/openclaw' && (matrix.runner || 'blacksmith-8vcpu-windows-2025') || 'windows-2025') }}
     timeout-minutes: 60
     env:
       NODE_OPTIONS: --max-old-space-size=8192
@@ -1763,6 +1830,7 @@ jobs:
         shell: bash
     strategy:
       fail-fast: false
+      max-parallel: 2
       matrix: ${{ fromJson(needs.preflight.outputs.checks_windows_matrix) }}
     steps:
       - name: Checkout
@@ -2092,6 +2160,7 @@ jobs:
     timeout-minutes: 20
     strategy:
       fail-fast: false
+      max-parallel: 2
       matrix: ${{ fromJson(needs.preflight.outputs.android_matrix) }}
     steps:
       - name: Checkout

.github/workflows/codeql-critical-quality.yml

@@ -96,7 +96,7 @@ on:
       - "src/auto-reply/reply/post-compaction-context.ts"
       - "src/auto-reply/reply/queue/**"
       - "src/auto-reply/reply/startup-context.ts"
-      - "src/commands/doctor-cron-dreaming-payload-migration.ts"
+      - "src/commands/doctor/cron/dreaming-payload-migration.ts"
       - "src/commands/doctor-memory-search.ts"
       - "src/commands/doctor-session-*.ts"
       - "src/commands/session-store-targets.ts"
@@ -257,7 +257,7 @@ jobs:
                 packages/gateway-protocol/src/*|packages/gateway-protocol/src/**/*|src/gateway/method-scopes.ts|src/gateway/server-methods/*|src/gateway/server-methods.ts|src/gateway/server-methods-list.ts)
                   gateway=true
                   ;;
-                packages/memory-host-sdk/*|src/commands/doctor-cron-dreaming-payload-migration.ts|src/commands/doctor-memory-search.ts|src/gateway/server-startup-memory.ts|src/memory/*|src/memory-host-sdk/*)
+                packages/memory-host-sdk/*|src/commands/doctor/cron/dreaming-payload-migration.ts|src/commands/doctor-memory-search.ts|src/gateway/server-startup-memory.ts|src/memory/*|src/memory-host-sdk/*)
                   memory=true
                   ;;
                 src/infra/outbound/base-session-key.ts|src/infra/outbound/delivery-queue*.ts|src/infra/outbound/outbound-session.ts|src/infra/outbound/session-binding*.ts|src/infra/outbound/session-context.ts|src/infra/outbound/targets-session.ts)
@@ -295,7 +295,7 @@ jobs:
                 src/model-catalog/*|src/plugins/*provider*.ts|src/plugins/capability-provider-runtime.ts|src/plugins/compaction-provider.ts|src/plugins/memory-embedding-provider*.ts|src/plugins/memory-embedding-providers*.ts|src/plugins/migration-provider-runtime.ts|src/plugins/synthetic-auth.runtime.ts|src/plugins/web-fetch-providers*.ts|src/plugins/web-search-providers*.ts)
                   provider=true
                   ;;
-                src/plugins/activation-planner.ts|src/plugins/api-builder.ts|src/plugins/bundled-*.ts|src/plugins/captured-registration.ts|src/plugins/config-*.ts|src/plugins/discovery.ts|src/plugins/effective-plugin-ids.ts|src/plugins/externalized-bundled-plugins.ts|src/plugins/installed-plugin-index*.ts|src/plugins/loader*.ts|src/plugins/manifest*.ts|src/plugins/module-export.ts|src/plugins/package-entrypoints.ts|src/plugins/plugin-registry*.ts|src/plugins/public-surface*.ts|src/plugins/registry.ts|src/plugins/registry-types.ts|src/plugins/runtime|src/plugins/runtime/*|src/plugins/runtime-state.ts|src/plugins/runtime.ts|src/plugins/sdk-alias.ts|src/plugins/source-loader.ts|src/plugins/types.ts|src/plugins/validation-diagnostics.ts)
+                src/plugins/activation-planner.ts|src/plugins/api-builder.ts|src/plugins/bundled-*.ts|src/plugins/captured-registration.ts|src/plugins/config-*.ts|src/plugins/discovery.ts|src/plugins/effective-plugin-ids.ts|src/plugins/externalized-bundled-plugins.ts|src/plugins/installed-plugin-index*.ts|src/plugins/loader*.ts|src/plugins/manifest*.ts|src/plugins/module-export.ts|src/plugins/package-entrypoints.ts|src/plugins/plugin-registry*.ts|src/plugins/public-surface*.ts|src/plugins/registry.ts|src/plugins/registry-types.ts|src/plugins/runtime|src/plugins/runtime/*|src/plugins/runtime-state.ts|src/plugins/runtime.ts|src/plugins/sdk-alias.ts|src/plugins/types.ts|src/plugins/validation-diagnostics.ts)
                   plugin=true
                   ;;
                 packages/plugin-package-contract/*|packages/plugin-sdk/*)

.github/workflows/openclaw-stable-main-closeout.yml

@@ -244,6 +244,11 @@ jobs:
             exit 1
           fi
           if [[ -z "$ROLLBACK_DRILL_ID" || -z "$ROLLBACK_DRILL_DATE" ]]; then
+            if [[ "$EVENT_NAME" == "push" ]]; then
+              echo "::warning::Stable closeout skipped: rollback drill repository variables are missing; manual dispatch remains required to complete closeout."
+              echo "should_closeout=false" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
             echo "Stable closeout requires repository variables RELEASE_ROLLBACK_DRILL_ID and RELEASE_ROLLBACK_DRILL_DATE, or explicit manual overrides." >&2
             exit 1
           fi

.github/workflows/workflow-sanity.yml

@@ -129,11 +129,28 @@ jobs:
           trusted_config="$RUNNER_TEMP/pre-commit-base.yaml"
           trusted_zizmor_config="$RUNNER_TEMP/zizmor-base.yml"
 
-          if ! git cat-file -e "${BASE_SHA}^{commit}" 2>/dev/null; then
-            timeout --signal=TERM --kill-after=10s 30s git fetch --no-tags --depth=1 origin \
-              "+${BASE_SHA}:refs/remotes/origin/security-base" ||
+          fetch_base_ref() {
+            local ref="$1"
+            local target="$2"
+            local fetch_status
+            for attempt in 1 2 3; do
               timeout --signal=TERM --kill-after=10s 30s git fetch --no-tags --depth=1 origin \
-                "+refs/heads/${BASE_REF}:refs/remotes/origin/${BASE_REF}"
+                "+${ref}:${target}" && return 0
+              fetch_status="$?"
+              if [ "$fetch_status" != "124" ] && [ "$fetch_status" != "137" ]; then
+                return "$fetch_status"
+              fi
+              if [ "$attempt" = "3" ]; then
+                return "$fetch_status"
+              fi
+              echo "::warning::trusted base fetch for '$ref' timed out on attempt $attempt; retrying"
+              sleep 5
+            done
+          }
+
+          if ! git cat-file -e "${BASE_SHA}^{commit}" 2>/dev/null; then
+            fetch_base_ref "$BASE_SHA" "refs/remotes/origin/security-base" ||
+              fetch_base_ref "refs/heads/${BASE_REF}" "refs/remotes/origin/${BASE_REF}"
           fi
 
           if git cat-file -e "${BASE_SHA}:.pre-commit-config.yaml" 2>/dev/null; then

apps/ios/Sources/Design/SettingsProTab.swift

@@ -54,6 +54,8 @@ struct SettingsProTab: View {
     @State var locationStatusText: String?
     @State var previousLocationModeRaw: String = OpenClawLocationMode.off.rawValue
     @State var notificationStatus: SettingsNotificationStatus = .checking
+    @State var isRequestingNotificationAuthorization = false
+    @State var showNotificationRelayDisclosure = false
     @State var diagnosticsLastRunText = "Not run"
     @State var diagnosticsIssueCount: Int?
     @State var showTalkIssueDetails = false
@@ -61,15 +63,18 @@ struct SettingsProTab: View {
     let initialRoute: SettingsRoute?
     let directRoute: SettingsRoute?
     let headerLeadingAction: OpenClawSidebarHeaderAction?
+    let onRouteChange: ((SettingsRoute?) -> Void)?
 
     init(
         initialRoute: SettingsRoute? = nil,
         directRoute: SettingsRoute? = nil,
-        headerLeadingAction: OpenClawSidebarHeaderAction? = nil)
+        headerLeadingAction: OpenClawSidebarHeaderAction? = nil,
+        onRouteChange: ((SettingsRoute?) -> Void)? = nil)
     {
         self.initialRoute = initialRoute
         self.directRoute = directRoute
         self.headerLeadingAction = headerLeadingAction
+        self.onRouteChange = onRouteChange
     }
 
     var body: some View {
@@ -117,6 +122,7 @@ struct SettingsProTab: View {
                 self.refreshNotificationSettings()
                 self.applyPendingGatewaySetupLinkIfNeeded()
                 self.applyInitialRouteIfNeeded()
+                self.notifyRouteChange()
             }
             .onChange(of: self.scenePhase) { _, phase in
                 if phase == .active {
@@ -153,6 +159,9 @@ struct SettingsProTab: View {
             .onChange(of: self.appModel.gatewaySetupRequestID) { _, _ in
                 self.applyPendingGatewaySetupLinkIfNeeded()
             }
+            .onChange(of: self.navigationPath) { _, _ in
+                self.notifyRouteChange()
+            }
     }
 
     private func settingsModalPresentation(_ content: some View) -> some View {
@@ -217,6 +226,19 @@ struct SettingsProTab: View {
             } message: {
                 Text(self.scannerError ?? "")
             }
+            .alert("Enable OpenClaw Hosted Push Relay?", isPresented: self.$showNotificationRelayDisclosure) {
+                    Button("Continue") {
+                        self.requestNotificationAuthorizationFromSettings()
+                    }
+                    Button("Not Now", role: .cancel) {}
+                } message: {
+                    Text(self.notificationRelayDisclosureMessage)
+                }
+    }
+
+    func openNotificationsRouteFromApprovals() {
+        guard self.directRoute == nil else { return }
+        self.navigationPath = [.notifications]
     }
 
     private func applyInitialRouteIfNeeded() {
@@ -225,4 +247,12 @@ struct SettingsProTab: View {
         guard self.navigationPath != [initialRoute] else { return }
         self.navigationPath = [initialRoute]
     }
+
+    private func notifyRouteChange() {
+        if let directRoute {
+            self.onRouteChange?(directRoute)
+            return
+        }
+        self.onRouteChange?(self.navigationPath.last)
+    }
 }

apps/ios/Sources/Design/SettingsProTabActions.swift

@@ -426,15 +426,30 @@ extension SettingsProTab {
             self.openNotificationSettings()
             return
         }
+        guard self.notificationStatus == .notSet else { return }
 
+        if PushBuildConfig.current.usesOpenClawHostedRelay {
+            self.showNotificationRelayDisclosure = true
+            return
+        }
+        self.requestNotificationAuthorizationFromSettings()
+    }
+
+    func requestNotificationAuthorizationFromSettings() {
+        guard !self.isRequestingNotificationAuthorization else { return }
+        self.isRequestingNotificationAuthorization = true
         Task {
             let granted = await (try? UNUserNotificationCenter.current().requestAuthorization(options: [
                 .alert,
                 .badge,
                 .sound,
             ])) ?? false
+            let settings = await UNUserNotificationCenter.current().notificationSettings()
             await MainActor.run {
-                self.notificationStatus = granted ? .allowed : .notAllowed
+                self.isRequestingNotificationAuthorization = false
+                self.notificationStatus = SettingsNotificationStatus(settings.authorizationStatus)
+                guard granted, self.notificationStatus.allowsNotifications else { return }
+                UIApplication.shared.registerForRemoteNotifications()
             }
         }
     }
@@ -661,6 +676,9 @@ extension SettingsProTab {
         if self.appModel.isAppleReviewDemoModeEnabled {
             return "Live gateway requests are disabled in demo mode."
         }
+        if self.notificationsNeedAttention {
+            return "Foreground approvals still appear while OpenClaw is connected."
+        }
         return self.gatewayConnected ? "Gateway requests will appear here." : "Connect to the gateway."
     }
 
@@ -700,7 +718,19 @@ extension SettingsProTab {
     }
 
     var approvalsDetail: String {
-        self.pendingApproval == nil ? "No approvals waiting" : "1 request waiting"
+        if self.notificationsNeedAttention {
+            return self.pendingApproval == nil ? "Notifications off" : "1 waiting, notifications off"
+        }
+        return self.pendingApproval == nil ? "No approvals waiting" : "1 request waiting"
+    }
+
+    var notificationsNeedAttention: Bool {
+        switch self.notificationStatus {
+        case .allowed, .checking:
+            false
+        case .notAllowed, .notSet, .unknown:
+            true
+        }
     }
 
     var approvalItems: [SettingsApprovalItem] {
@@ -771,4 +801,33 @@ extension SettingsProTab {
     var notificationActionText: String {
         self.notificationStatus.actionTitle
     }
+
+    var notificationStatusDetail: String {
+        switch self.notificationStatus {
+        case .checking:
+            "Checking iOS notification permission."
+        case .allowed:
+            "OpenClaw can show approval prompts and event alerts when the app is not active."
+        case .notAllowed:
+            "Notifications have been denied. Enable them in iOS Settings."
+        case .notSet:
+            "Enable notifications to receive approval prompts and event alerts outside the app."
+        case .unknown:
+            "OpenClaw cannot determine the current notification permission state."
+        }
+    }
+
+    var notificationRelayDetail: String {
+        if PushBuildConfig.current.usesOpenClawHostedRelay {
+            return """
+            This build uses OpenClaw's hosted push relay at ios-push-relay.openclaw.ai for notification \
+            delivery data.
+            """
+        }
+        return "This build is not configured to use OpenClaw's hosted push relay."
+    }
+
+    var notificationRelayDisclosureMessage: String {
+        "Enabling this sends delivery data through OpenClaw's hosted push relay."
+    }
 }

apps/ios/Sources/Design/SettingsProTabSections.swift

@@ -308,15 +308,57 @@ extension SettingsProTab {
             self.detailStatusCard(
                 icon: "checkmark.shield.fill",
                 title: "Approvals",
-                detail: self.pendingApproval == nil ? "No gateway actions are waiting for review." :
-                    "Review the pending gateway action.",
-                value: self.pendingApproval == nil ? "clear" : "1 waiting",
-                color: self.pendingApproval == nil ? OpenClawBrand.ok : OpenClawBrand.warn)
+                detail: self.notificationsNeedAttention
+                    ? "Out-of-app approval alerts need notification permission."
+                    : (self.pendingApproval == nil ? "No gateway actions are waiting for review." :
+                        "Review the pending gateway action."),
+                value: self.notificationsNeedAttention
+                    ? "Alerts Off"
+                    : (self.pendingApproval == nil ? "clear" : "1 waiting"),
+                color: self.notificationsNeedAttention ? OpenClawBrand.warn :
+                    (self.pendingApproval == nil ? OpenClawBrand.ok : OpenClawBrand.warn))
+
+            if self.notificationsNeedAttention {
+                self.approvalNotificationsWarningCard
+            }
 
             self.approvalsReviewCard
         }
     }
 
+    var approvalNotificationsWarningCard: some View {
+        ProCard(radius: SettingsLayout.cardRadius) {
+            VStack(alignment: .leading, spacing: 12) {
+                HStack(alignment: .top, spacing: 12) {
+                    ProIconBadge(systemName: "bell.slash.fill", color: OpenClawBrand.warn)
+                    VStack(alignment: .leading, spacing: 4) {
+                        Text("Notifications are off")
+                            .font(.subheadline.weight(.semibold))
+                        Text(
+                            """
+                            Enable Notifications to receive approval notifications while OpenClaw is not open.
+                            """)
+                            .font(.caption)
+                            .foregroundStyle(.secondary)
+                            .fixedSize(horizontal: false, vertical: true)
+                    }
+                }
+
+                if self.directRoute == nil {
+                    Button {
+                        self.openNotificationsRouteFromApprovals()
+                    } label: {
+                        Label("Open Notifications", systemImage: "bell.badge")
+                            .frame(maxWidth: .infinity)
+                    }
+                    .buttonStyle(.bordered)
+                    .controlSize(.small)
+                }
+            }
+        }
+        .padding(.horizontal, OpenClawProMetric.pagePadding)
+    }
+
     var approvalsReviewCard: some View {
         ProCard(radius: SettingsLayout.cardRadius) {
             VStack(alignment: .leading, spacing: 12) {
@@ -490,7 +532,7 @@ extension SettingsProTab {
             self.detailStatusCard(
                 icon: "bell",
                 title: "Notifications",
-                detail: "Approvals and event alerts from OpenClaw.",
+                detail: self.notificationStatusDetail,
                 value: self.notificationStatusText,
                 color: self.notificationStatus.color)
 
@@ -506,10 +548,25 @@ extension SettingsProTab {
                     }
                     .buttonStyle(.borderedProminent)
                     .controlSize(.small)
+                    .disabled(self.notificationStatus == .checking || self.isRequestingNotificationAuthorization)
 
-                    Text("OpenClaw uses notifications for approval prompts and mirrored event alerts.")
+                    Text(self.notificationStatusDetail)
                         .font(.caption)
                         .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+
+                    Divider()
+
+                    HStack(alignment: .top, spacing: 10) {
+                        Image(systemName: "network")
+                            .font(.caption.weight(.semibold))
+                            .foregroundStyle(OpenClawBrand.accent)
+                            .frame(width: 22, height: 22)
+                        Text(self.notificationRelayDetail)
+                            .font(.caption)
+                            .foregroundStyle(.secondary)
+                            .fixedSize(horizontal: false, vertical: true)
+                    }
                 }
             }
             .padding(.horizontal, OpenClawProMetric.pagePadding)

apps/ios/Sources/Design/SettingsProTabSupport.swift

@@ -89,28 +89,48 @@ enum SettingsNotificationStatus: Equatable {
     var text: String {
         switch self {
         case .checking: "Checking"
-        case .allowed: "Allowed"
-        case .notAllowed: "Not Allowed"
-        case .notSet: "Not Set"
+        case .allowed: "Enabled"
+        case .notAllowed: "Denied"
+        case .notSet: "Not Enabled"
         case .unknown: "Unknown"
         }
     }
 
     var actionTitle: String {
         switch self {
-        case .notSet, .checking:
-            "Request Access"
-        case .allowed, .notAllowed, .unknown:
-            "Open System Settings"
+        case .notSet:
+            "Enable Notifications"
+        case .checking:
+            "Checking"
+        case .allowed:
+            "Manage in iOS Settings"
+        case .notAllowed, .unknown:
+            "Open iOS Settings"
         }
     }
 
     var actionIcon: String {
-        self == .allowed ? "gear" : "bell.badge"
+        switch self {
+        case .allowed:
+            "gear"
+        case .notAllowed, .unknown:
+            "gear.badge"
+        case .checking:
+            "hourglass"
+        case .notSet:
+            "bell.badge"
+        }
     }
 
     var color: Color {
-        self == .allowed ? OpenClawBrand.ok : .secondary
+        switch self {
+        case .allowed:
+            OpenClawBrand.ok
+        case .notAllowed, .unknown:
+            OpenClawBrand.warn
+        case .checking, .notSet:
+            .secondary
+        }
     }
 
     var shouldOpenNotificationSettings: Bool {
@@ -121,6 +141,10 @@ enum SettingsNotificationStatus: Equatable {
             false
         }
     }
+
+    var allowsNotifications: Bool {
+        self == .allowed
+    }
 }
 
 enum SettingsDiagnosticIssue: String, Equatable, CaseIterable {

apps/ios/Sources/Gateway/ExecApprovalPromptDialog.swift

@@ -2,11 +2,14 @@ import SwiftUI
 
 private struct ExecApprovalPromptDialogModifier: ViewModifier {
     @Environment(NodeAppModel.self) private var appModel: NodeAppModel
+    let suppressedApprovalID: String?
 
     func body(content: Content) -> some View {
         content
             .overlay {
-                if let prompt = self.appModel.pendingExecApprovalPrompt {
+                if let prompt = self.appModel.pendingExecApprovalPrompt,
+                   prompt.id != self.suppressedApprovalID
+                {
                     ZStack {
                         Color.black.opacity(0.38)
                             .ignoresSafeArea()
@@ -58,7 +61,7 @@ private struct ExecApprovalPromptCard: View {
             VStack(alignment: .leading, spacing: 6) {
                 Text("Exec approval required")
                     .font(.headline)
-                Text("OpenClaw opened from a notification. Review this exec request before continuing.")
+                Text("Review this exec request before continuing. Your decision will be sent back to the gateway.")
                     .font(.subheadline)
                     .foregroundStyle(.secondary)
             }
@@ -188,7 +191,7 @@ private struct ExecApprovalPromptMetadataRow: View {
 }
 
 extension View {
-    func execApprovalPromptDialog() -> some View {
-        self.modifier(ExecApprovalPromptDialogModifier())
+    func execApprovalPromptDialog(suppressedApprovalID: String? = nil) -> some View {
+        self.modifier(ExecApprovalPromptDialogModifier(suppressedApprovalID: suppressedApprovalID))
     }
 }

apps/ios/Sources/Gateway/NotificationPermissionGuidanceDialog.swift

@@ -0,0 +1,102 @@
+import SwiftUI
+
+private struct NotificationPermissionGuidanceDialogModifier: ViewModifier {
+    @Environment(NodeAppModel.self) private var appModel: NodeAppModel
+    let openNotifications: (String) -> Void
+
+    func body(content: Content) -> some View {
+        content
+            .overlay {
+                if let prompt = self.appModel.pendingNotificationPermissionGuidancePrompt {
+                    ZStack {
+                        Color.black.opacity(0.38)
+                            .ignoresSafeArea()
+
+                        NotificationPermissionGuidanceCard(
+                            onOpenNotifications: {
+                                let approvalId = prompt.approvalId
+                                self.appModel.dismissNotificationPermissionGuidancePrompt(
+                                    suppressFuture: false)
+                                self.openNotifications(approvalId)
+                            },
+                            onDismiss: {
+                                self.appModel.dismissNotificationPermissionGuidancePrompt(
+                                    suppressFuture: false)
+                            },
+                            onSuppressFuture: {
+                                self.appModel.dismissNotificationPermissionGuidancePrompt(
+                                    suppressFuture: true)
+                            })
+                            .padding(.horizontal, 20)
+                            .frame(maxWidth: 460)
+                            .transition(.scale(scale: 0.98).combined(with: .opacity))
+                    }
+                    .zIndex(2)
+                    .id(prompt.id)
+                }
+            }
+            .animation(
+                .easeInOut(duration: 0.18),
+                value: self.appModel.pendingNotificationPermissionGuidancePrompt?.id)
+    }
+}
+
+private struct NotificationPermissionGuidanceCard: View {
+    let onOpenNotifications: () -> Void
+    let onDismiss: () -> Void
+    let onSuppressFuture: () -> Void
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 14) {
+            VStack(alignment: .leading, spacing: 6) {
+                Text("Notifications are off")
+                    .font(.headline)
+                Text(
+                    """
+                    Exec approvals can only be reviewed while OpenClaw is open and connected.
+
+                    Enable Notifications to receive approval notifications while OpenClaw is not open.
+                    """)
+                    .font(.subheadline)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+
+            VStack(spacing: 10) {
+                Button {
+                    self.onOpenNotifications()
+                } label: {
+                    Text("Open Notifications Settings")
+                        .frame(maxWidth: .infinity)
+                }
+                .buttonStyle(.borderedProminent)
+
+                Button(role: .cancel) {
+                    self.onDismiss()
+                } label: {
+                    Text("Not Now")
+                        .frame(maxWidth: .infinity)
+                }
+                .buttonStyle(.bordered)
+
+                Button {
+                    self.onSuppressFuture()
+                } label: {
+                    Text("Don't show again")
+                        .frame(maxWidth: .infinity)
+                }
+                .buttonStyle(.bordered)
+            }
+            .controlSize(.large)
+            .frame(maxWidth: .infinity)
+        }
+        .padding(18)
+        .proPanelSurface(tint: OpenClawBrand.warn, radius: 20, isProminent: true)
+    }
+}
+
+extension View {
+    func notificationPermissionGuidanceDialog(openNotifications: @escaping (String) -> Void) -> some View {
+        self.modifier(NotificationPermissionGuidanceDialogModifier(openNotifications: openNotifications))
+    }
+}

apps/ios/Sources/Model/NodeAppModel.swift

@@ -87,6 +87,11 @@ final class NodeAppModel {
         }
     }
 
+    struct NotificationPermissionGuidancePrompt: Identifiable, Equatable {
+        let id = UUID()
+        let approvalId: String
+    }
+
     private enum ExecApprovalResolutionOutcome {
         case resolved
         case stale
@@ -100,6 +105,8 @@ final class NodeAppModel {
     }
 
     private let deepLinkLogger = Logger(subsystem: "ai.openclawfoundation.app", category: "DeepLink")
+    private nonisolated static let execApprovalNotificationGuidanceSuppressedKey =
+        "notifications.execApprovalGuidance.suppressed"
     private let pushWakeLogger = Logger(subsystem: "ai.openclawfoundation.app", category: "PushWake")
     private let pendingActionLogger = Logger(subsystem: "ai.openclawfoundation.app", category: "PendingAction")
     private let locationWakeLogger = Logger(subsystem: "ai.openclawfoundation.app", category: "LocationWake")
@@ -160,6 +167,7 @@ final class NodeAppModel {
     private(set) var pendingExecApprovalPromptResolving: Bool = false
     private(set) var pendingExecApprovalPromptErrorText: String?
     private var pendingExecApprovalPromptRequestGeneration: Int = 0
+    private(set) var pendingNotificationPermissionGuidancePrompt: NotificationPermissionGuidancePrompt?
     private var queuedAgentDeepLinkPrompt: AgentDeepLinkPrompt?
     private var lastAgentDeepLinkPromptAt: Date = .distantPast
     @ObservationIgnored private var queuedAgentDeepLinkPromptTask: Task<Void, Never>?
@@ -921,6 +929,7 @@ final class NodeAppModel {
             self.applyTalkModeSync(enabled: decoded.enabled, phase: decoded.phase)
         case ExecApprovalNotificationBridge.requestedKind:
             guard let approvalId = Self.execApprovalEventID(from: payload) else { return }
+            await self.presentNotificationPermissionGuidanceForExecApprovalIfNeeded(approvalId: approvalId)
             await self.presentExecApprovalNotificationPrompt(
                 ExecApprovalNotificationPrompt(approvalId: approvalId))
         case ExecApprovalNotificationBridge.resolvedKind:
@@ -1359,8 +1368,8 @@ final class NodeAppModel {
                 error: OpenClawNodeError(code: .invalidRequest, message: "INVALID_REQUEST: empty notification"))
         }
 
-        let finalStatus = await self.requestNotificationAuthorizationIfNeeded()
-        guard finalStatus == .authorized || finalStatus == .provisional || finalStatus == .ephemeral else {
+        let status = await self.notificationAuthorizationStatus()
+        guard Self.isNotificationAuthorizationAllowed(status) else {
             return BridgeInvokeResponse(
                 id: req.id,
                 ok: false,
@@ -1412,9 +1421,18 @@ final class NodeAppModel {
                 error: OpenClawNodeError(code: .invalidRequest, message: "INVALID_REQUEST: empty chat.push text"))
         }
 
-        let finalStatus = await self.requestNotificationAuthorizationIfNeeded()
+        let shouldSpeak = params.speak ?? true
+        let status = await self.notificationAuthorizationStatus()
+        let notificationsAllowed = Self.isNotificationAuthorizationAllowed(status)
+        if !notificationsAllowed, !shouldSpeak {
+            return BridgeInvokeResponse(
+                id: req.id,
+                ok: false,
+                error: OpenClawNodeError(code: .unavailable, message: "NOT_AUTHORIZED: notifications"))
+        }
+
         let messageId = UUID().uuidString
-        if finalStatus == .authorized || finalStatus == .provisional || finalStatus == .ephemeral {
+        if notificationsAllowed {
             let addResult = await self.runNotificationCall(timeoutSeconds: 2.0) { [notificationCenter] in
                 let content = UNMutableNotificationContent()
                 content.title = "OpenClaw"
@@ -1435,7 +1453,7 @@ final class NodeAppModel {
             }
         }
 
-        if params.speak ?? true {
+        if shouldSpeak {
             let toSpeak = text
             Task { @MainActor in
                 try? await TalkSystemSpeechSynthesizer.shared.speak(text: toSpeak)
@@ -1447,26 +1465,6 @@ final class NodeAppModel {
         return BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: json)
     }
 
-    private func requestNotificationAuthorizationIfNeeded() async -> NotificationAuthorizationStatus {
-        let status = await self.notificationAuthorizationStatus()
-        guard status == .notDetermined else { return status }
-
-        // Avoid hanging invoke requests if the permission prompt is never answered.
-        _ = await self.runNotificationCall(timeoutSeconds: 2.0) { [notificationCenter] in
-            _ = try await notificationCenter.requestAuthorization(options: [.alert, .sound, .badge])
-        }
-
-        let updatedStatus = await self.notificationAuthorizationStatus()
-        if Self.isNotificationAuthorizationAllowed(updatedStatus) {
-            // Refresh APNs registration immediately after the first permission grant so the
-            // gateway can receive a push registration without requiring an app relaunch.
-            await MainActor.run {
-                UIApplication.shared.registerForRemoteNotifications()
-            }
-        }
-        return updatedStatus
-    }
-
     private func notificationAuthorizationStatus() async -> NotificationAuthorizationStatus {
         let result = await self.runNotificationCall(timeoutSeconds: 1.5) { [notificationCenter] in
             await notificationCenter.authorizationStatus()
@@ -1490,6 +1488,29 @@ final class NodeAppModel {
         }
     }
 
+    private func presentNotificationPermissionGuidanceForExecApprovalIfNeeded(approvalId: String) async {
+        guard !self.execApprovalNotificationGuidanceSuppressed else { return }
+        let status = await self.notificationAuthorizationStatus()
+        guard !Self.isNotificationAuthorizationAllowed(status) else { return }
+        self.pendingNotificationPermissionGuidancePrompt =
+            NotificationPermissionGuidancePrompt(approvalId: approvalId)
+    }
+
+    var execApprovalNotificationGuidanceSuppressed: Bool {
+        UserDefaults.standard.bool(forKey: Self.execApprovalNotificationGuidanceSuppressedKey)
+    }
+
+    func dismissNotificationPermissionGuidancePrompt(suppressFuture: Bool) {
+        if suppressFuture {
+            UserDefaults.standard.set(true, forKey: Self.execApprovalNotificationGuidanceSuppressedKey)
+        }
+        self.pendingNotificationPermissionGuidancePrompt = nil
+    }
+
+    func resetExecApprovalNotificationGuidanceSuppression() {
+        UserDefaults.standard.removeObject(forKey: Self.execApprovalNotificationGuidanceSuppressedKey)
+    }
+
     private func runNotificationCall<T: Sendable>(
         timeoutSeconds: Double,
         operation: @escaping @Sendable () async throws -> T) async -> Result<T, NotificationCallError>
@@ -2362,10 +2383,6 @@ extension NodeAppModel {
                 nodeOptions: nodeOptions,
                 sessionBox: sessionBox)
         }
-
-        // QR bootstrap onboarding should surface the system notification permission
-        // prompt immediately so visible APNs alerts work without a second manual step.
-        _ = await self.requestNotificationAuthorizationIfNeeded()
     }
 
     private func refreshBackgroundReconnectSuppressionIfNeeded(source: String) {
@@ -3943,11 +3960,15 @@ extension NodeAppModel {
         let hadWatchPrompt = self.watchExecApprovalPromptsByID[normalizedApprovalID] != nil
         let hadPendingPrompt = self.pendingExecApprovalPrompt?.id == normalizedApprovalID
         let hadPendingRecoveryID = self.pendingWatchExecApprovalRecoveryIDs.contains(normalizedApprovalID)
-        guard hadWatchPrompt || hadPendingPrompt || hadPendingRecoveryID else {
+        let hadGuidancePrompt = self.pendingNotificationPermissionGuidancePrompt?.approvalId == normalizedApprovalID
+        let hadApprovalSurface = hadWatchPrompt || hadPendingPrompt || hadPendingRecoveryID
+        guard hadApprovalSurface || hadGuidancePrompt else {
             return
         }
 
-        await self.publishWatchExecApprovalExpired(approvalId: normalizedApprovalID, reason: .resolved)
+        if hadApprovalSurface {
+            await self.publishWatchExecApprovalExpired(approvalId: normalizedApprovalID, reason: .resolved)
+        }
         self.clearPendingExecApprovalPromptIfMatches(normalizedApprovalID)
     }
 
@@ -4428,10 +4449,17 @@ extension NodeAppModel {
 
     private func clearPendingExecApprovalPromptIfMatches(_ approvalId: String) {
         let normalizedApprovalID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
+        self.clearNotificationPermissionGuidancePromptIfMatches(normalizedApprovalID)
         guard self.pendingExecApprovalPrompt?.id == normalizedApprovalID else { return }
         self.dismissPendingExecApprovalPrompt()
     }
 
+    private func clearNotificationPermissionGuidancePromptIfMatches(_ approvalId: String) {
+        let normalizedApprovalID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard self.pendingNotificationPermissionGuidancePrompt?.approvalId == normalizedApprovalID else { return }
+        self.pendingNotificationPermissionGuidancePrompt = nil
+    }
+
     private nonisolated static func isApprovalNotificationStaleError(_ error: Error) -> Bool {
         guard let gatewayError = error as? GatewayResponseError else { return false }
         if gatewayError.code != "INVALID_REQUEST" {
@@ -5137,6 +5165,20 @@ extension NodeAppModel {
         self.pendingExecApprovalPrompt
     }
 
+    func _test_pendingNotificationPermissionGuidancePrompt() -> NotificationPermissionGuidancePrompt? {
+        self.pendingNotificationPermissionGuidancePrompt
+    }
+
+    func _debug_presentNotificationPermissionGuidancePromptForScreenshot() {
+        self.resetExecApprovalNotificationGuidanceSuppression()
+        self.pendingNotificationPermissionGuidancePrompt =
+            NotificationPermissionGuidancePrompt(approvalId: "screenshot-exec-approval")
+    }
+
+    func _test_resetExecApprovalNotificationGuidanceSuppression() {
+        self.resetExecApprovalNotificationGuidanceSuppression()
+    }
+
     func _test_recordPendingWatchExecApprovalRecoveryID(_ approvalId: String) {
         self.appendPendingWatchExecApprovalRecoveryID(approvalId)
     }
@@ -5270,24 +5312,6 @@ extension NodeAppModel {
     func _test_restartGatewaySessionsAfterForegroundStaleConnection() async {
         await self.restartGatewaySessionsAfterForegroundStaleConnection()
     }
-
-    func _test_handleSuccessfulBootstrapGatewayOnboarding() async {
-        await self.handleSuccessfulBootstrapGatewayOnboarding(
-            url: URL(string: "wss://gateway.example")!,
-            stableID: "test-gateway",
-            token: nil,
-            password: nil,
-            nodeOptions: GatewayConnectOptions(
-                role: "node",
-                scopes: [],
-                caps: [],
-                commands: [],
-                permissions: [:],
-                clientId: "openclaw-ios",
-                clientMode: "node",
-                clientDisplayName: nil),
-            sessionBox: nil)
-    }
 }
 #endif
 // swiftlint:enable type_body_length file_length

apps/ios/Sources/OpenClawApp.swift

@@ -409,7 +409,7 @@ enum WatchPromptNotificationBridge {
         let title = params.title.trimmingCharacters(in: .whitespacesAndNewlines)
         let body = params.body.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !title.isEmpty || !body.isEmpty else { return }
-        guard await self.requestNotificationAuthorizationIfNeeded() else { return }
+        guard await self.isNotificationAuthorizationAllowed() else { return }
 
         let normalizedActions = (params.actions ?? []).compactMap { action -> OpenClawWatchAction? in
             let id = action.id.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -516,29 +516,10 @@ enum WatchPromptNotificationBridge {
         }
     }
 
-    private static func requestNotificationAuthorizationIfNeeded() async -> Bool {
+    private static func isNotificationAuthorizationAllowed() async -> Bool {
         let center = UNUserNotificationCenter.current()
         let status = await self.notificationAuthorizationStatus(center: center)
-        switch status {
-        case .authorized, .provisional, .ephemeral:
-            return true
-        case .notDetermined:
-            let granted = await (try? center.requestAuthorization(options: [.alert, .sound, .badge])) ?? false
-            if !granted { return false }
-            let updatedStatus = await self.notificationAuthorizationStatus(center: center)
-            if self.isAuthorizationStatusAllowed(updatedStatus) {
-                // Refresh APNs registration immediately after the first permission grant so the
-                // gateway can receive a push registration without requiring an app relaunch.
-                await MainActor.run {
-                    UIApplication.shared.registerForRemoteNotifications()
-                }
-            }
-            return self.isAuthorizationStatusAllowed(updatedStatus)
-        case .denied:
-            return false
-        @unknown default:
-            return false
-        }
+        return self.isAuthorizationStatusAllowed(status)
     }
 
     private static func isAuthorizationStatusAllowed(_ status: UNAuthorizationStatus) -> Bool {
@@ -635,6 +616,9 @@ struct OpenClawApp: App {
             UserDefaults.standard.set(true, forKey: "gateway.hasConnectedOnce")
             UserDefaults.standard.set(true, forKey: "onboarding.quickSetupDismissed")
             appModel.enterScreenshotFixtureMode()
+            if Self.screenshotNotificationGuidanceEnabled {
+                appModel._debug_presentNotificationPermissionGuidancePromptForScreenshot()
+            }
         }
         #endif
         OpenClawAppModelRegistry.appModel = appModel
@@ -686,6 +670,14 @@ struct OpenClawApp: App {
         #endif
     }
 
+    private static var screenshotNotificationGuidanceEnabled: Bool {
+        #if DEBUG
+        ProcessInfo.processInfo.arguments.contains("--openclaw-screenshot-notification-guidance")
+        #else
+        false
+        #endif
+    }
+
     @MainActor
     private func applyAppearancePreference() {
         let style = self.appearancePreference.userInterfaceStyle

apps/ios/Sources/Push/PushBuildConfig.swift

@@ -22,6 +22,20 @@ struct PushBuildConfig {
     let apnsEnvironment: PushAPNsEnvironment
 
     static let current = PushBuildConfig()
+    static let openClawHostedRelayHost = "ios-push-relay.openclaw.ai"
+
+    var usesOpenClawHostedRelay: Bool {
+        guard self.transport == .relay, self.distribution == .official else { return false }
+        guard let relayBaseURL = self.relayBaseURL,
+              let components = URLComponents(url: relayBaseURL, resolvingAgainstBaseURL: false)
+        else {
+            return false
+        }
+        return components.scheme?.lowercased() == "https"
+            && components.host?.lowercased() == Self.openClawHostedRelayHost
+            && components.user == nil
+            && components.password == nil
+    }
 
     init(bundle: Bundle = .main) {
         self.transport = Self.readEnum(

apps/ios/Sources/RootTabs.swift

@@ -24,6 +24,8 @@ struct RootTabs: View {
         AppAppearancePreference.system.rawValue
     @State private var selectedTab: AppTab = Self.initialTab
     @State private var selectedSidebarDestination: SidebarDestination = Self.initialSidebarDestination
+    @State private var selectedSettingsRoute: SettingsRoute? = Self.initialSidebarDestination.settingsRoute
+    @State private var selectedSettingsRouteRequestID: Int = 0
     @State private var isSidebarVisible: Bool = Self.initialSidebarVisibility ?? false
     @State private var sidebarVisibilityUserOverridden: Bool = Self.initialSidebarVisibility != nil
     @State private var isSidebarDrawerLayout: Bool = false
@@ -39,6 +41,7 @@ struct RootTabs: View {
     @State private var didApplyInitialAppearance: Bool = false
     @State private var didApplyInitialChatSession: Bool = false
     @State private var handledGatewaySetupRequestID: Int = 0
+    @State private var suppressedExecApprovalPromptIDForNotificationSettings: String?
 
     private static var initialTab: AppTab {
         let arguments = ProcessInfo.processInfo.arguments
@@ -161,8 +164,10 @@ struct RootTabs: View {
             .tabItem { Label("Agent", systemImage: "person.2.fill") }
             .tag(AppTab.agent)
 
-            SettingsProTab(initialRoute: self.selectedSidebarDestination.settingsRoute)
-                .id(self.selectedSidebarDestination.settingsRoute.map { "\($0)" } ?? "settings")
+            SettingsProTab(
+                initialRoute: self.selectedSettingsRoute,
+                onRouteChange: self.handleSettingsRouteChange)
+                .id(self.settingsTabViewID)
                 .tabItem { Label("Settings", systemImage: "gearshape.fill") }
                 .tag(AppTab.settings)
         }
@@ -235,7 +240,7 @@ struct RootTabs: View {
 
     private var sidebarDetailShell: some View {
         self.sidebarDetail
-            .id(self.selectedSidebarDestination.id)
+            .id(self.sidebarDetailShellID)
     }
 
     private var sidebarColumn: some View {
@@ -463,11 +468,21 @@ struct RootTabs: View {
                 headerLeadingAction: self.sidebarHeaderLeadingAction,
                 gatewayAction: { self.selectSidebarDestination(.gateway) })
         case .settings:
-            SettingsProTab(headerLeadingAction: self.sidebarHeaderLeadingAction)
+            if let selectedSettingsRoute {
+                SettingsProTab(
+                    directRoute: selectedSettingsRoute,
+                    headerLeadingAction: self.sidebarHeaderLeadingAction,
+                    onRouteChange: self.handleSettingsRouteChange)
+            } else {
+                SettingsProTab(
+                    headerLeadingAction: self.sidebarHeaderLeadingAction,
+                    onRouteChange: self.handleSettingsRouteChange)
+            }
         case .gateway:
             SettingsProTab(
-                directRoute: self.selectedSidebarDestination.settingsRoute ?? .gateway,
-                headerLeadingAction: self.sidebarHeaderLeadingAction)
+                directRoute: self.selectedSettingsRoute ?? self.selectedSidebarDestination.settingsRoute ?? .gateway,
+                headerLeadingAction: self.sidebarHeaderLeadingAction,
+                onRouteChange: self.handleSettingsRouteChange)
         }
     }
 
@@ -492,6 +507,21 @@ struct RootTabs: View {
         return UIDevice.current.userInterfaceIdiom
     }
 
+    private var sidebarDetailShellID: String {
+        let routeID = self.selectedSettingsRoute.map { "\($0)" } ?? "root"
+        return "\(self.selectedSidebarDestination.id):\(routeID):\(self.selectedSettingsRouteRequestID)"
+    }
+
+    private var settingsTabViewID: String {
+        let routeID = self.selectedSettingsRoute.map { "\($0)" } ?? "settings"
+        return "\(routeID):\(self.selectedSettingsRouteRequestID)"
+    }
+
+    private var activeExecApprovalPromptSuppressionID: String? {
+        guard self.selectedTab == .settings, self.selectedSettingsRoute == .notifications else { return nil }
+        return self.suppressedExecApprovalPromptIDForNotificationSettings
+    }
+
     private var shouldCollapseSidebarAfterSelection: Bool {
         Self.shouldCollapseSidebarAfterSelection(
             layoutMode: self.isSidebarDrawerLayout ? .drawer : .split)
@@ -705,6 +735,11 @@ struct RootTabs: View {
             .onChange(of: self.appModel.gatewaySetupRequestID) { _, _ in
                 self.maybeOpenSettingsForGatewaySetup()
             }
+            .onChange(of: self.appModel.pendingExecApprovalPrompt?.id) { _, newValue in
+                if newValue != self.suppressedExecApprovalPromptIDForNotificationSettings {
+                    self.suppressedExecApprovalPromptIDForNotificationSettings = nil
+                }
+            }
     }
 
     private func rootPresentation(_ content: some View) -> some View {
@@ -742,7 +777,12 @@ struct RootTabs: View {
             }
             .gatewayTrustPromptAlert()
             .deepLinkAgentPromptAlert()
-            .execApprovalPromptDialog()
+            .execApprovalPromptDialog(
+                suppressedApprovalID: self.activeExecApprovalPromptSuppressionID)
+            .notificationPermissionGuidanceDialog(openNotifications: { approvalId in
+                self.suppressedExecApprovalPromptIDForNotificationSettings = approvalId
+                self.selectSettingsRoute(.notifications)
+            })
     }
 
     private var appearancePreference: AppAppearancePreference {
@@ -874,9 +914,15 @@ struct RootTabs: View {
     private func homeCanvasName(for agent: AgentSummary) -> String {
         self.normalized(agent.name) ?? agent.id
     }
+}
 
+extension RootTabs {
     private func selectSidebarDestination(_ destination: SidebarDestination) {
+        if destination.settingsRoute != .notifications {
+            self.suppressedExecApprovalPromptIDForNotificationSettings = nil
+        }
         self.selectedSidebarDestination = destination
+        self.selectedSettingsRoute = destination.settingsRoute
         self.selectedTab = destination.appTab
         guard self.usesSidebarTabs, self.shouldCollapseSidebarAfterSelection else { return }
         withAnimation(.easeInOut(duration: 0.22)) {
@@ -884,6 +930,31 @@ struct RootTabs: View {
         }
     }
 
+    private func selectSettingsRoute(_ route: SettingsRoute) {
+        if route != .notifications {
+            self.suppressedExecApprovalPromptIDForNotificationSettings = nil
+        }
+        self.selectedSettingsRoute = route
+        self.selectedSettingsRouteRequestID &+= 1
+        self.selectedSidebarDestination = .settings
+        self.selectedTab = .settings
+        guard self.usesSidebarTabs, self.shouldCollapseSidebarAfterSelection else { return }
+        withAnimation(.easeInOut(duration: 0.22)) {
+            self.setSidebarVisible(false)
+        }
+    }
+
+    private func handleSettingsRouteChange(_ route: SettingsRoute?) {
+        guard route != .notifications else { return }
+        if route == nil {
+            self.selectedSettingsRoute = nil
+            if self.selectedTab == .settings {
+                self.selectedSidebarDestination = .settings
+            }
+        }
+        self.suppressedExecApprovalPromptIDForNotificationSettings = nil
+    }
+
     private func showSidebar() {
         self.sidebarVisibilityUserOverridden = true
         withAnimation(.easeInOut(duration: 0.22)) {

apps/ios/Sources/Services/NotificationService.swift

@@ -16,7 +16,6 @@ enum NotificationAuthorizationStatus {
 
 protocol NotificationCentering: Sendable {
     func authorizationStatus() async -> NotificationAuthorizationStatus
-    func requestAuthorization(options: UNAuthorizationOptions) async throws -> Bool
     func add(_ request: UNNotificationRequest) async throws
     func removePendingNotificationRequests(withIdentifiers identifiers: [String]) async
     func removeDeliveredNotifications(withIdentifiers identifiers: [String]) async
@@ -48,10 +47,6 @@ struct LiveNotificationCenter: NotificationCentering, @unchecked Sendable {
         }
     }
 
-    func requestAuthorization(options: UNAuthorizationOptions) async throws -> Bool {
-        try await self.center.requestAuthorization(options: options)
-    }
-
     func add(_ request: UNNotificationRequest) async throws {
         try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
             self.center.add(request) { error in

apps/ios/SwiftSources.input.xcfilelist

@@ -50,6 +50,7 @@ Sources/Gateway/GatewayDiscoveryModel.swift
 Sources/Gateway/GatewayHealthMonitor.swift
 Sources/Gateway/GatewayProblemView.swift
 Sources/Gateway/GatewayQuickSetupSheet.swift
+Sources/Gateway/NotificationPermissionGuidanceDialog.swift
 Sources/Gateway/GatewayServiceResolver.swift
 Sources/Gateway/GatewaySettingsStore.swift
 Sources/Gateway/GatewayTrustPromptAlert.swift

apps/ios/Tests/ExecApprovalNotificationBridgeTests.swift

@@ -14,10 +14,6 @@ private final class MockNotificationCenter: NotificationCentering, @unchecked Se
         self.authorization
     }
 
-    func requestAuthorization(options _: UNAuthorizationOptions) async throws -> Bool {
-        true
-    }
-
     func add(_ request: UNNotificationRequest) async throws {
         self.addedRequests.append(request)
     }

apps/ios/Tests/NodeAppModelInvokeTests.swift

@@ -200,25 +200,16 @@ private final class MockWatchMessagingService: @preconcurrency WatchMessagingSer
 
 private final class MockBootstrapNotificationCenter: NotificationCentering, @unchecked Sendable {
     var status: NotificationAuthorizationStatus = .notDetermined
-    var requestAuthorizationResult = false
-    var requestAuthorizationCalls = 0
+    var addCalls = 0
 
     func authorizationStatus() async -> NotificationAuthorizationStatus {
         self.status
     }
 
-    func requestAuthorization(options _: UNAuthorizationOptions) async throws -> Bool {
-        self.requestAuthorizationCalls += 1
-        if self.requestAuthorizationResult {
-            self.status = .authorized
-        } else {
-            self.status = .denied
-        }
-        return self.requestAuthorizationResult
+    func add(_: UNNotificationRequest) async throws {
+        self.addCalls += 1
     }
 
-    func add(_: UNNotificationRequest) async throws {}
-
     func removePendingNotificationRequests(withIdentifiers _: [String]) async {}
 
     func removeDeliveredNotifications(withIdentifiers _: [String]) async {}
@@ -1230,13 +1221,65 @@ private final class MockBootstrapNotificationCenter: NotificationCentering, @unc
                 hasStoredOperatorToken: false))
     }
 
-    @Test @MainActor func successfulBootstrapOnboardingRequestsNotificationAuthorization() async {
+    @Test @MainActor func operatorGatewayRequestedEventShowsNotificationGuidanceWhenNotificationsOff() async throws {
         let center = MockBootstrapNotificationCenter()
+        center.status = .notDetermined
         let appModel = NodeAppModel(notificationCenter: center)
+        appModel._test_resetExecApprovalNotificationGuidanceSuppression()
+        defer { appModel._test_resetExecApprovalNotificationGuidanceSuppression() }
 
-        await appModel._test_handleSuccessfulBootstrapGatewayOnboarding()
+        await appModel._test_handleOperatorGatewayServerEvent(EventFrame(
+            type: "event",
+            event: ExecApprovalNotificationBridge.requestedKind,
+            payload: AnyCodable(["id": "approval-notifications-off"]),
+            seq: nil,
+            stateversion: nil))
 
-        #expect(center.requestAuthorizationCalls == 1)
+        let prompt = try #require(appModel._test_pendingNotificationPermissionGuidancePrompt())
+        #expect(prompt.approvalId == "approval-notifications-off")
+    }
+
+    @Test @MainActor func suppressedOperatorGatewayRequestedEventDoesNotShowNotificationGuidance() async {
+        let center = MockBootstrapNotificationCenter()
+        center.status = .denied
+        let appModel = NodeAppModel(notificationCenter: center)
+        appModel._test_resetExecApprovalNotificationGuidanceSuppression()
+        defer { appModel._test_resetExecApprovalNotificationGuidanceSuppression() }
+        appModel.dismissNotificationPermissionGuidancePrompt(suppressFuture: true)
+
+        await appModel._test_handleOperatorGatewayServerEvent(EventFrame(
+            type: "event",
+            event: ExecApprovalNotificationBridge.requestedKind,
+            payload: AnyCodable(["id": "approval-suppressed"]),
+            seq: nil,
+            stateversion: nil))
+
+        #expect(appModel._test_pendingNotificationPermissionGuidancePrompt() == nil)
+    }
+
+    @Test @MainActor func operatorGatewayResolvedEventClearsNotificationGuidancePrompt() async throws {
+        let center = MockBootstrapNotificationCenter()
+        center.status = .denied
+        let appModel = NodeAppModel(notificationCenter: center)
+        appModel._test_resetExecApprovalNotificationGuidanceSuppression()
+        defer { appModel._test_resetExecApprovalNotificationGuidanceSuppression() }
+
+        await appModel._test_handleOperatorGatewayServerEvent(EventFrame(
+            type: "event",
+            event: ExecApprovalNotificationBridge.requestedKind,
+            payload: AnyCodable(["id": "approval-guidance-resolved"]),
+            seq: nil,
+            stateversion: nil))
+        _ = try #require(appModel._test_pendingNotificationPermissionGuidancePrompt())
+
+        await appModel._test_handleOperatorGatewayServerEvent(EventFrame(
+            type: "event",
+            event: ExecApprovalNotificationBridge.resolvedKind,
+            payload: AnyCodable(["id": "approval-guidance-resolved"]),
+            seq: nil,
+            stateversion: nil))
+
+        #expect(appModel._test_pendingNotificationPermissionGuidancePrompt() == nil)
     }
 
     @Test func clearingBootstrapTokenStripsReconnectConfigEvenWithoutPersistence() throws {
@@ -1298,6 +1341,78 @@ private final class MockBootstrapNotificationCenter: NotificationCentering, @unc
         #expect(res.error?.message.contains("CAMERA_DISABLED") == true)
     }
 
+    @Test @MainActor func systemNotifyReturnsUnavailableWhenNotificationsOff() async throws {
+        let center = MockBootstrapNotificationCenter()
+        center.status = .notDetermined
+        let appModel = NodeAppModel(notificationCenter: center)
+        let params = OpenClawSystemNotifyParams(title: "Approval", body: "Review request")
+        let paramsData = try JSONEncoder().encode(params)
+        let req = BridgeInvokeRequest(
+            id: "notify-off",
+            command: OpenClawSystemCommand.notify.rawValue,
+            paramsJSON: String(decoding: paramsData, as: UTF8.self))
+
+        let res = await appModel._test_handleInvoke(req)
+
+        #expect(res.ok == false)
+        #expect(res.error?.code == .unavailable)
+        #expect(res.error?.message == "NOT_AUTHORIZED: notifications")
+        #expect(center.addCalls == 0)
+    }
+
+    @Test @MainActor func systemNotifySchedulesWhenNotificationsAreAlreadyAllowed() async throws {
+        let center = MockBootstrapNotificationCenter()
+        center.status = .authorized
+        let appModel = NodeAppModel(notificationCenter: center)
+        let params = OpenClawSystemNotifyParams(title: "Approval", body: "Review request")
+        let paramsData = try JSONEncoder().encode(params)
+        let req = BridgeInvokeRequest(
+            id: "notify-on",
+            command: OpenClawSystemCommand.notify.rawValue,
+            paramsJSON: String(decoding: paramsData, as: UTF8.self))
+
+        let res = await appModel._test_handleInvoke(req)
+
+        #expect(res.ok)
+        #expect(center.addCalls == 1)
+    }
+
+    @Test @MainActor func chatPushWithoutSpeechReturnsUnavailableWhenNotificationsOff() async throws {
+        let center = MockBootstrapNotificationCenter()
+        center.status = .notDetermined
+        let appModel = NodeAppModel(notificationCenter: center)
+        let params = OpenClawChatPushParams(text: "Build finished", speak: false)
+        let paramsData = try JSONEncoder().encode(params)
+        let req = BridgeInvokeRequest(
+            id: "chat-push-off",
+            command: OpenClawChatCommand.push.rawValue,
+            paramsJSON: String(decoding: paramsData, as: UTF8.self))
+
+        let res = await appModel._test_handleInvoke(req)
+
+        #expect(res.ok == false)
+        #expect(res.error?.code == .unavailable)
+        #expect(res.error?.message == "NOT_AUTHORIZED: notifications")
+        #expect(center.addCalls == 0)
+    }
+
+    @Test @MainActor func chatPushSchedulesWhenNotificationsAreAlreadyAllowed() async throws {
+        let center = MockBootstrapNotificationCenter()
+        center.status = .authorized
+        let appModel = NodeAppModel(notificationCenter: center)
+        let params = OpenClawChatPushParams(text: "Build finished", speak: false)
+        let paramsData = try JSONEncoder().encode(params)
+        let req = BridgeInvokeRequest(
+            id: "chat-push-on",
+            command: OpenClawChatCommand.push.rawValue,
+            paramsJSON: String(decoding: paramsData, as: UTF8.self))
+
+        let res = await appModel._test_handleInvoke(req)
+
+        #expect(res.ok)
+        #expect(center.addCalls == 1)
+    }
+
     @Test @MainActor func handleInvokeRejectsInvalidScreenFormat() async {
         let appModel = NodeAppModel()
         let params = OpenClawScreenRecordParams(format: "gif")

apps/ios/Tests/RootTabsSourceGuardTests.swift

@@ -1,8 +1,8 @@
 import Foundation
 import Testing
 
-@Suite struct RootTabsSourceGuardTests {
-    @Test func hiddenSidebarRevealUsesDestinationHeaderWithoutReservedRail() throws {
+struct RootTabsSourceGuardTests {
+    @Test func `hidden sidebar reveal uses destination header without reserved rail`() throws {
         let source = try String(contentsOf: Self.rootTabsSourceURL(), encoding: .utf8)
         let componentSource = try String(contentsOf: Self.proComponentsSourceURL(), encoding: .utf8)
 
@@ -38,7 +38,7 @@ import Testing
         #expect(!source.contains("shouldShowOverviewHeaderSidebarReveal"))
     }
 
-    @Test func iPadSplitUsesSlidingSidebarWhilePortraitKeepsDrawerOverlay() throws {
+    @Test func `i pad split uses sliding sidebar while portrait keeps drawer overlay`() throws {
         let source = try String(contentsOf: Self.rootTabsSourceURL(), encoding: .utf8)
         let splitContent = try Self.extract(
             source,
@@ -67,7 +67,7 @@ import Testing
         #expect(!drawerContent.contains("NavigationSplitView"))
     }
 
-    @Test func sidebarKeepsNavigationModelDestinationOnly() throws {
+    @Test func `sidebar keeps navigation model destination only`() throws {
         let source = try String(contentsOf: Self.rootTabsSourceURL(), encoding: .utf8)
         let navigationSource = try String(contentsOf: Self.rootTabsNavigationSourceURL(), encoding: .utf8)
         let sidebarColumn = try Self.extract(
@@ -114,7 +114,7 @@ import Testing
         #expect(navigationSource.contains("SidebarGroup(title: \"REFERENCE\", destinations: [.docs])"))
     }
 
-    @Test func sidebarRoutesUseDestinationHeadersInsteadOfRepeatedProductBranding() throws {
+    @Test func `sidebar routes use destination headers instead of repeated product branding`() throws {
         let rootSource = try String(contentsOf: Self.rootTabsSourceURL(), encoding: .utf8)
         let agentOverviewSource = try String(contentsOf: Self.agentProTabOverviewSourceURL(), encoding: .utf8)
         let docsSource = try String(contentsOf: Self.docsSourceURL(), encoding: .utf8)
@@ -148,7 +148,7 @@ import Testing
         #expect(!docsSource.contains("Text(\"OpenClaw Docs\")"))
     }
 
-    @Test func agentsDirectRouteKeepsSingleSidebarControl() throws {
+    @Test func `agents direct route keeps single sidebar control`() throws {
         let source = try String(contentsOf: Self.agentProTabSourceURL(), encoding: .utf8)
         let destinationsSource = try String(contentsOf: Self.agentProTabDestinationsSourceURL(), encoding: .utf8)
         let nodesSource = try String(contentsOf: Self.agentProNodesDestinationSourceURL(), encoding: .utf8)
@@ -165,7 +165,7 @@ import Testing
         #expect(dreamingSource.contains("OpenClawSidebarHeaderLeadingSlot(action: headerLeadingAction)"))
     }
 
-    @Test func routedHeadersUseSharedAdaptiveLayout() throws {
+    @Test func `routed headers use shared adaptive layout`() throws {
         let componentsSource = try String(contentsOf: Self.proComponentsSourceURL(), encoding: .utf8)
         let featureChromeSource = try String(contentsOf: Self.iPadSidebarScreenChromeSourceURL(), encoding: .utf8)
         let docsSource = try String(contentsOf: Self.docsSourceURL(), encoding: .utf8)
@@ -187,7 +187,7 @@ import Testing
         #expect(settingsSource.contains("OpenClawAdaptiveHeaderRow("))
     }
 
-    @Test func phoneHubKeepsDocsAsDestinationOnly() throws {
+    @Test func `phone hub keeps docs as destination only`() throws {
         let source = try String(contentsOf: Self.phoneHubSourceURL(), encoding: .utf8)
 
         #expect(source.contains("case .docs:"))
@@ -198,7 +198,7 @@ import Testing
         #expect(!source.contains("https://docs.openclaw.ai"))
     }
 
-    @Test func rootShellPreviewMatrixCoversPhoneAndIPadStates() throws {
+    @Test func `root shell preview matrix covers phone and I pad states`() throws {
         let source = try String(contentsOf: Self.rootTabsSourceURL(), encoding: .utf8)
 
         #expect(source.contains("#Preview(\n    \"Shell iPhone portrait\""))
@@ -211,7 +211,7 @@ import Testing
         #expect(source.contains("#Preview(\n    \"Shell iPad gateway error\""))
     }
 
-    @Test func sharedChatPreviewMatrixCoversConnectionStates() throws {
+    @Test func `shared chat preview matrix covers connection states`() throws {
         let source = try String(contentsOf: Self.sharedChatPreviewSourceURL(), encoding: .utf8)
 
         #expect(source.contains("#Preview(\"Chat connected\")"))
@@ -226,7 +226,7 @@ import Testing
         #expect(source.contains("Gateway not connected. Check Tailscale and retry."))
     }
 
-    @Test func phoneHubKeepsContentAboveFloatingTabBar() throws {
+    @Test func `phone hub keeps content above floating tab bar`() throws {
         let source = try String(contentsOf: Self.phoneHubSourceURL(), encoding: .utf8)
 
         #expect(source.contains(".safeAreaPadding(.bottom, self.bottomScrollInset)"))
@@ -235,7 +235,7 @@ import Testing
         #expect(!source.contains("bottomTabBarClearance"))
     }
 
-    @Test func phoneHubHeaderStaysTaskFirst() throws {
+    @Test func `phone hub header stays task first`() throws {
         let source = try String(contentsOf: Self.phoneHubSourceURL(), encoding: .utf8)
 
         #expect(source.contains("private var gatewayActionRow: some View"))
@@ -253,7 +253,7 @@ import Testing
         #expect(!source.contains("private func metric(label:"))
     }
 
-    @Test func workboardUsesRealGatewayMethods() throws {
+    @Test func `workboard uses real gateway methods`() throws {
         let source = try String(contentsOf: Self.iPadWorkboardScreenSourceURL(), encoding: .utf8)
 
         #expect(source.contains("workboard.cards.list"))
@@ -268,7 +268,7 @@ import Testing
         #expect(!source.contains("Multi-column queue control"))
     }
 
-    @Test func workboardCreateActionSurfacesUnavailableReasons() throws {
+    @Test func `workboard create action surfaces unavailable reasons`() throws {
         let source = try String(contentsOf: Self.iPadWorkboardScreenSourceURL(), encoding: .utf8)
         let createFunction = try Self.extract(
             source,
@@ -295,7 +295,7 @@ import Testing
         #expect(createFunction.contains("return true"))
     }
 
-    @Test func taskScopeControlsSendRealGatewayParams() throws {
+    @Test func `task scope controls send real gateway params`() throws {
         let source = try Self.iPadTaskFeatureScreensSource()
 
         #expect(source.contains("private var boardScopeMenu: some View"))
@@ -314,7 +314,7 @@ import Testing
                 "params: EmptyParams(),\n                timeoutSeconds: 20)\n            let response = try JSONDecoder().decode(IPadSkillProposalManifest.self"))
     }
 
-    @Test func compactTaskRowsKeepPhoneNativeActions() throws {
+    @Test func `compact task rows keep phone native actions`() throws {
         let source = try Self.iPadTaskFeatureScreensSource()
         let compactControls = try Self.extract(
             source,
@@ -348,7 +348,7 @@ import Testing
         #expect(compactControls.contains("Label(\"Dispatch\""))
     }
 
-    @Test func skillWorkshopUsesKanbanLanesOnWideIPad() throws {
+    @Test func `skill workshop uses kanban lanes on wide I pad`() throws {
         let source = try String(contentsOf: Self.iPadSkillWorkshopScreenSourceURL(), encoding: .utf8)
         let previewSource = try String(contentsOf: Self.iPadSidebarFeaturePreviewsSourceURL(), encoding: .utf8)
         let content = try Self.extract(
@@ -376,7 +376,7 @@ import Testing
         #expect(previewSource.contains("status: \"manual_QA\""))
     }
 
-    @Test func compactTaskRowsHavePopulatedPhonePreviews() throws {
+    @Test func `compact task rows have populated phone previews`() throws {
         let source = try String(contentsOf: Self.iPadSidebarFeaturePreviewsSourceURL(), encoding: .utf8)
 
         #expect(source.contains("#Preview(\"Workboard phone queue rows\")"))
@@ -387,7 +387,7 @@ import Testing
         #expect(source.contains("IPadSkillWorkshopPreviewFixtures.proposals"))
     }
 
-    @Test func taskScreenPreviewMatricesCoverPrimaryStates() throws {
+    @Test func `task screen preview matrices cover primary states`() throws {
         let source = try String(contentsOf: Self.iPadSidebarFeaturePreviewsSourceURL(), encoding: .utf8)
 
         #expect(source.contains("#Preview(\"Workboard states\")"))
@@ -412,7 +412,7 @@ import Testing
         #expect(source.contains("\"manual_QA\""))
     }
 
-    @Test func activityPreviewMatrixCoversConnectionStates() throws {
+    @Test func `activity preview matrix covers connection states`() throws {
         let source = try String(contentsOf: Self.iPadSidebarFeaturePreviewsSourceURL(), encoding: .utf8)
 
         #expect(source.contains("#Preview(\"Activity states\")"))
@@ -426,7 +426,7 @@ import Testing
         #expect(source.contains("title: \"Loading sessions\""))
     }
 
-    @Test func routedFeatureScreensReuseSharedProComponents() throws {
+    @Test func `routed feature screens reuse shared pro components`() throws {
         let source = try Self.iPadTaskFeatureScreensSource()
         let componentsSource = try String(contentsOf: Self.proComponentsSourceURL(), encoding: .utf8)
         let channelsSource = try String(contentsOf: Self.channelsSourceURL(), encoding: .utf8)
@@ -445,20 +445,22 @@ import Testing
         #expect(componentsSource.contains("struct ProStatusRow"))
     }
 
-    @Test func activityScreenStaysSplitFromTaskFeatureScreens() throws {
+    @Test func `activity screen stays split from task feature screens`() throws {
         let taskSource = try Self.iPadTaskFeatureScreensSource()
         let activitySource = try String(contentsOf: Self.iPadActivityScreenSourceURL(), encoding: .utf8)
+        let appModelSource = try String(contentsOf: Self.nodeAppModelSourceURL(), encoding: .utf8)
         let projectSource = try String(contentsOf: Self.xcodeProjectSourceURL(), encoding: .utf8)
 
         #expect(activitySource.contains("struct IPadActivityScreen: View"))
-        #expect(activitySource.contains("IOSGatewayChatTransport(gateway: self.appModel.operatorSession)"))
+        #expect(activitySource.contains("self.appModel.makeChatTransport()"))
+        #expect(appModelSource.contains("return IOSGatewayChatTransport(gateway: self.operatorSession)"))
         #expect(activitySource.contains("IPadSidebarScreenChrome("))
         #expect(!taskSource.contains("struct IPadActivityScreen"))
         #expect(!taskSource.contains("import OpenClawChatUI"))
         #expect(projectSource.contains("IPadActivityScreen.swift in Sources"))
     }
 
-    @Test func routedFeatureChromeStaysSplitFromTaskFeatureScreens() throws {
+    @Test func `routed feature chrome stays split from task feature screens`() throws {
         let taskSource = try Self.iPadTaskFeatureScreensSource()
         let chromeSource = try String(contentsOf: Self.iPadSidebarScreenChromeSourceURL(), encoding: .utf8)
         let projectSource = try String(contentsOf: Self.xcodeProjectSourceURL(), encoding: .utf8)
@@ -470,7 +472,7 @@ import Testing
         #expect(projectSource.contains("IPadSidebarScreenChrome.swift in Sources"))
     }
 
-    @Test func routedFeatureChromeKeepsGatewayPillActionable() throws {
+    @Test func `routed feature chrome keeps gateway pill actionable`() throws {
         let chromeSource = try String(contentsOf: Self.iPadSidebarScreenChromeSourceURL(), encoding: .utf8)
         let featureSource = try Self.iPadTaskFeatureScreensSource()
         let rootSource = try String(contentsOf: Self.rootTabsSourceURL(), encoding: .utf8)
@@ -486,14 +488,18 @@ import Testing
             .count == 1)
     }
 
-    @Test func routedGatewayPillsOpenGatewaySettings() throws {
+    @Test func `routed gateway pills open gateway settings`() throws {
         let rootSource = try String(contentsOf: Self.rootTabsSourceURL(), encoding: .utf8)
         let agentSource = try String(contentsOf: Self.agentProTabSourceURL(), encoding: .utf8)
         let agentOverviewSource = try String(contentsOf: Self.agentProTabOverviewSourceURL(), encoding: .utf8)
         let overviewSource = try String(contentsOf: Self.commandCenterSourceURL(), encoding: .utf8)
         let chatSource = try String(contentsOf: Self.chatProTabSourceURL(), encoding: .utf8)
         let docsSource = try String(contentsOf: Self.docsSourceURL(), encoding: .utf8)
+        let settingsTabSource = try String(contentsOf: Self.settingsProTabSourceURL(), encoding: .utf8)
         let settingsSource = try String(contentsOf: Self.settingsProTabSectionsSourceURL(), encoding: .utf8)
+        let notificationGuidanceSource = try String(
+            contentsOf: Self.notificationPermissionGuidanceDialogSourceURL(),
+            encoding: .utf8)
 
         #expect(rootSource.matches(of: /openSettings: \{ self\.selectSidebarDestination\(\.gateway\) \}/).count >= 2)
         #expect(rootSource.matches(of: /gatewayAction: \{ self\.selectSidebarDestination\(\.gateway\) \}/).count == 1)
@@ -512,15 +518,39 @@ import Testing
         #expect(docsSource.contains("let gatewayAction: (() -> Void)?"))
         #expect(settingsSource.contains("NavigationLink(value: SettingsRoute.gateway)"))
         #expect(rootSource.contains("case .settings:"))
-        #expect(rootSource.contains("SettingsProTab(headerLeadingAction: self.sidebarHeaderLeadingAction)"))
-        #expect(rootSource.contains("directRoute: self.selectedSidebarDestination.settingsRoute ?? .gateway"))
-        #expect(rootSource.contains("SettingsProTab(initialRoute: self.selectedSidebarDestination.settingsRoute)"))
+        #expect(rootSource
+            .matches(of: /SettingsProTab\(\s*headerLeadingAction: self\.sidebarHeaderLeadingAction,/)
+            .count >= 1)
+        #expect(rootSource
+            .contains(
+                "directRoute: self.selectedSettingsRoute ?? self.selectedSidebarDestination.settingsRoute ?? .gateway"))
+        #expect(rootSource.matches(of: /SettingsProTab\(\s*initialRoute: self\.selectedSettingsRoute,/).count == 1)
+        #expect(rootSource.contains(".id(self.settingsTabViewID)"))
+        #expect(rootSource.contains("@State private var selectedSettingsRouteRequestID: Int = 0"))
+        #expect(rootSource.contains("self.selectedSettingsRouteRequestID &+= 1"))
+        #expect(rootSource.contains("@State private var suppressedExecApprovalPromptIDForNotificationSettings"))
+        #expect(rootSource.contains("private var activeExecApprovalPromptSuppressionID: String?"))
+        #expect(rootSource.contains("suppressedApprovalID: self.activeExecApprovalPromptSuppressionID"))
+        #expect(rootSource.contains("if destination.settingsRoute != .notifications"))
+        #expect(rootSource.contains("if route != .notifications"))
+        #expect(rootSource.contains("if route == nil"))
+        #expect(rootSource.contains("self.selectedSettingsRoute = nil"))
+        #expect(rootSource.contains("self.selectedSidebarDestination = .settings"))
+        #expect(rootSource.contains("self.suppressedExecApprovalPromptIDForNotificationSettings = approvalId"))
+        #expect(rootSource.contains("onRouteChange: self.handleSettingsRouteChange"))
+        #expect(rootSource.contains("private func handleSettingsRouteChange(_ route: SettingsRoute?)"))
+        #expect(settingsTabSource.contains("let onRouteChange: ((SettingsRoute?) -> Void)?"))
+        #expect(settingsTabSource.contains("self.onRouteChange?(self.navigationPath.last)"))
+        #expect(notificationGuidanceSource.contains("onSuppressFuture"))
+        #expect(notificationGuidanceSource.contains("suppressFuture: true"))
+        #expect(notificationGuidanceSource.contains("Text(\"Don't show again\")"))
+        #expect(rootSource.contains("private func selectSettingsRoute(_ route: SettingsRoute)"))
         #expect(settingsSource.contains("title: \"Channels / Integrations\""))
         #expect(settingsSource.contains("route: .channels"))
         #expect(docsSource.contains(".accessibilityHint(\"Opens Settings / Gateway\")"))
     }
 
-    @Test func gatewaySettingsKeepsPairingTrustDiagnosticsAndTailscaleActions() throws {
+    @Test func `gateway settings keeps pairing trust diagnostics and tailscale actions`() throws {
         let settingsSource = try String(contentsOf: Self.settingsProTabSourceURL(), encoding: .utf8)
         let sectionsSource = try String(contentsOf: Self.settingsProTabSectionsSourceURL(), encoding: .utf8)
         let actionsSource = try String(contentsOf: Self.settingsProTabActionsSourceURL(), encoding: .utf8)
@@ -566,7 +596,7 @@ import Testing
         #expect(controllerSource.contains("trustRotatedGatewayCertificate(from problem: GatewayConnectionProblem)"))
     }
 
-    @Test func gatewaySettingsPreviewMatrixCoversPrimaryStates() throws {
+    @Test func `gateway settings preview matrix covers primary states`() throws {
         let supportSource = try String(contentsOf: Self.settingsProTabSupportSourceURL(), encoding: .utf8)
 
         #expect(supportSource.contains("#Preview(\"Gateway settings states\")"))
@@ -585,12 +615,15 @@ import Testing
         #expect(supportSource.contains("self.previewButton(\"Diagnose\""))
     }
 
-    @Test func nativeChatUsesGatewayTransport() throws {
+    @Test func `native chat uses gateway transport`() throws {
         let chatSource = try String(contentsOf: Self.chatProTabSourceURL(), encoding: .utf8)
         let channelsSource = try String(contentsOf: Self.channelsSourceURL(), encoding: .utf8)
+        let settingsSectionsSource = try String(contentsOf: Self.settingsProTabSectionsSourceURL(), encoding: .utf8)
+        let appModelSource = try String(contentsOf: Self.nodeAppModelSourceURL(), encoding: .utf8)
 
-        #expect(chatSource.contains("IOSGatewayChatTransport(gateway: self.appModel.operatorSession)"))
-        #expect(channelsSource.contains("Message routing and external channel clients."))
+        #expect(chatSource.matches(of: /self\.appModel\.makeChatTransport\(\)/).count == 2)
+        #expect(appModelSource.contains("return IOSGatewayChatTransport(gateway: self.operatorSession)"))
+        #expect(settingsSectionsSource.contains("Message routing and external channel clients."))
         #expect(channelsSource.contains("\"clickclack\": SettingsChannelFallbackMetadata"))
         #expect(channelsSource.contains("label: \"ClickClack\""))
         #expect(channelsSource.contains("Self-hosted chat bot routing."))
@@ -603,6 +636,13 @@ import Testing
             .appendingPathComponent("Sources/RootTabs.swift")
     }
 
+    private static func nodeAppModelSourceURL() -> URL {
+        URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .appendingPathComponent("Sources/Model/NodeAppModel.swift")
+    }
+
     private static func phoneHubSourceURL() -> URL {
         URL(fileURLWithPath: #filePath)
             .deletingLastPathComponent()
@@ -746,6 +786,13 @@ import Testing
             .appendingPathComponent("Sources/Design/SettingsProTab.swift")
     }
 
+    private static func notificationPermissionGuidanceDialogSourceURL() -> URL {
+        URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .appendingPathComponent("Sources/Gateway/NotificationPermissionGuidanceDialog.swift")
+    }
+
     private static func settingsProTabActionsSourceURL() -> URL {
         URL(fileURLWithPath: #filePath)
             .deletingLastPathComponent()

apps/shared/OpenClawKit/Sources/OpenClawKit/Resources/tool-display.json

@@ -69,6 +69,17 @@
         "fileName"
       ]
     },
+    "api": {
+      "emoji": "🌐",
+      "title": "API",
+      "detailKeys": [
+        "url",
+        "endpoint",
+        "path",
+        "method",
+        "name"
+      ]
+    },
     "browser": {
       "emoji": "🌐",
       "title": "Browser",

apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift

@@ -7277,7 +7277,9 @@ public struct ChatSendParams: Codable, Sendable {
     public let sessionid: String?
     public let message: String
     public let thinking: String?
-    public let fastmode: Bool?
+    public let fastmodevalue: AnyCodable?
+    public var fastmode: Bool? { fastmodevalue?.value as? Bool }
+    public let fastautoonseconds: Int?
     public let deliver: Bool?
     public let originatingchannel: String?
     public let originatingto: String?
@@ -7290,6 +7292,46 @@ public struct ChatSendParams: Codable, Sendable {
     public let suppresscommandinterpretation: Bool?
     public let idempotencykey: String
 
+    public init(
+        sessionkey: String,
+        agentid: String? = nil,
+        sessionid: String?,
+        message: String,
+        thinking: String?,
+        fastmodevalue: AnyCodable?,
+        fastautoonseconds: Int?,
+        deliver: Bool?,
+        originatingchannel: String?,
+        originatingto: String?,
+        originatingaccountid: String?,
+        originatingthreadid: String?,
+        attachments: [AnyCodable]?,
+        timeoutms: Int?,
+        systeminputprovenance: [String: AnyCodable]?,
+        systemprovenancereceipt: String?,
+        suppresscommandinterpretation: Bool?,
+        idempotencykey: String)
+    {
+        self.sessionkey = sessionkey
+        self.agentid = agentid
+        self.sessionid = sessionid
+        self.message = message
+        self.thinking = thinking
+        self.fastmodevalue = fastmodevalue
+        self.fastautoonseconds = fastautoonseconds
+        self.deliver = deliver
+        self.originatingchannel = originatingchannel
+        self.originatingto = originatingto
+        self.originatingaccountid = originatingaccountid
+        self.originatingthreadid = originatingthreadid
+        self.attachments = attachments
+        self.timeoutms = timeoutms
+        self.systeminputprovenance = systeminputprovenance
+        self.systemprovenancereceipt = systemprovenancereceipt
+        self.suppresscommandinterpretation = suppresscommandinterpretation
+        self.idempotencykey = idempotencykey
+    }
+
     public init(
         sessionkey: String,
         agentid: String? = nil,
@@ -7309,23 +7351,25 @@ public struct ChatSendParams: Codable, Sendable {
         suppresscommandinterpretation: Bool?,
         idempotencykey: String)
     {
-        self.sessionkey = sessionkey
-        self.agentid = agentid
-        self.sessionid = sessionid
-        self.message = message
-        self.thinking = thinking
-        self.fastmode = fastmode
-        self.deliver = deliver
-        self.originatingchannel = originatingchannel
-        self.originatingto = originatingto
-        self.originatingaccountid = originatingaccountid
-        self.originatingthreadid = originatingthreadid
-        self.attachments = attachments
-        self.timeoutms = timeoutms
-        self.systeminputprovenance = systeminputprovenance
-        self.systemprovenancereceipt = systemprovenancereceipt
-        self.suppresscommandinterpretation = suppresscommandinterpretation
-        self.idempotencykey = idempotencykey
+        self.init(
+            sessionkey: sessionkey,
+            agentid: agentid,
+            sessionid: sessionid,
+            message: message,
+            thinking: thinking,
+            fastmodevalue: fastmode.map { AnyCodable($0) },
+            fastautoonseconds: nil,
+            deliver: deliver,
+            originatingchannel: originatingchannel,
+            originatingto: originatingto,
+            originatingaccountid: originatingaccountid,
+            originatingthreadid: originatingthreadid,
+            attachments: attachments,
+            timeoutms: timeoutms,
+            systeminputprovenance: systeminputprovenance,
+            systemprovenancereceipt: systemprovenancereceipt,
+            suppresscommandinterpretation: suppresscommandinterpretation,
+            idempotencykey: idempotencykey)
     }
 
     private enum CodingKeys: String, CodingKey {
@@ -7334,7 +7378,8 @@ public struct ChatSendParams: Codable, Sendable {
         case sessionid = "sessionId"
         case message
         case thinking
-        case fastmode = "fastMode"
+        case fastmodevalue = "fastMode"
+        case fastautoonseconds = "fastAutoOnSeconds"
         case deliver
         case originatingchannel = "originatingChannel"
         case originatingto = "originatingTo"

docs/.generated/config-baseline.sha256

@@ -1,4 +1,4 @@
-24f11880cec619997ff93d303c32431bf4fb2bfefb56c9f0ece35ff91b329a80  config-baseline.json
+3ac3be8b7e201eb577854806a9806ba90acbfb2616e14b3ffd1169f188620303  config-baseline.json
 2923c1120c0369aeca6646cd67f7264590c6a1f4e5bc3157a04d7661324c6868  config-baseline.core.json
-2d735389858305509528e74329b6f8c65d311e1471c3b4e91dc17aaab8e63a80  config-baseline.channel.json
+769899651e2769833ae7e9c8fbf402e55f3d5e32da6bfe21a9659cc35d1f07bb  config-baseline.channel.json
 d2e2114f1cd43dc894fe1a4836677b42a2a5af825537d6c4a932da832d58a590  config-baseline.plugin.json

docs/.generated/plugin-sdk-api-baseline.sha256

@@ -1,2 +1,2 @@
-172fe4e143964c0a20525428ff3e6c7631856a7d51c6ad48959a35c72363a410  plugin-sdk-api-baseline.json
-a4c18ea9f0b0d2c22183bf8c082e757b7f9852b4c518c8b8cb62a21a9dd766e9  plugin-sdk-api-baseline.jsonl
+05ce13ad6d2ef72af943a61a023e26f58d01e37a04f76e279a933df9b6aed05b  plugin-sdk-api-baseline.json
+628a6ac85acd5ed71236b07d5760e211b9c0698ea529d5b3101c20579926b0ea  plugin-sdk-api-baseline.jsonl

docs/automation/cron-jobs.md

@@ -183,7 +183,7 @@ Model-selection precedence for isolated jobs is:
 3. User-selected stored cron session model override
 4. Agent/default model selection
 
-Fast mode follows the resolved live selection too. If the selected model config has `params.fastMode`, isolated cron uses that by default. A stored session `fastMode` override still wins over config in either direction.
+Fast mode follows the resolved live selection too. If the selected model config has `params.fastMode`, isolated cron uses that by default. A stored session `fastMode` override still wins over config in either direction. Auto mode uses the selected model's `params.fastAutoOnSeconds` cutoff when present, defaulting to 60 seconds.
 
 If an isolated run hits a live model-switch handoff, cron retries with the switched provider/model and persists that live selection for the active run before retrying. When the switch also carries a new auth profile, cron persists that auth profile override for the active run too. Retries are bounded: after the initial attempt plus 2 switch retries, cron aborts instead of looping forever.
 

docs/channels/clickclack.md

@@ -63,9 +63,9 @@ If `plugins.allow` is a non-empty restrictive list, explicitly selecting
 ClickClack in channel setup or running `openclaw plugins enable clickclack`
 appends `clickclack` to that list. Onboarding installation uses the same
 explicit-selection behavior. These paths do not override `plugins.deny` or a
-global `plugins.enabled: false` setting. Direct `openclaw plugins install
-clickclack` follows the normal plugin-install policy and also records ClickClack
-in an existing allowlist.
+global `plugins.enabled: false` setting. Direct
+`openclaw plugins install @openclaw/clickclack` follows the normal
+plugin-install policy and also records ClickClack in an existing allowlist.
 
 ## Multiple bots
 

docs/channels/imessage-from-bluebubbles.md

@@ -94,28 +94,28 @@ Use this checklist when you already know your old BlueBubbles config and want th
 
 iMessage and BlueBubbles share a lot of channel-level config. The keys that change are mostly transport (REST server vs local CLI). Behavior keys (`dmPolicy`, `groupPolicy`, `allowFrom`, etc.) keep the same meaning.
 
-| BlueBubbles                                                | bundled iMessage                          | Notes                                                                                                                                                                                                                                                                                                                                        |
-| ---------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `channels.bluebubbles.enabled`                             | `channels.imessage.enabled`               | Same semantics.                                                                                                                                                                                                                                                                                                                              |
-| `channels.bluebubbles.serverUrl`                           | _(removed)_                               | No REST server — the plugin spawns `imsg rpc` over stdio.                                                                                                                                                                                                                                                                                    |
-| `channels.bluebubbles.password`                            | _(removed)_                               | No webhook authentication needed.                                                                                                                                                                                                                                                                                                            |
-| _(implicit)_                                               | `channels.imessage.cliPath`               | Path to `imsg` (default `imsg`); use a wrapper script for SSH.                                                                                                                                                                                                                                                                               |
-| _(implicit)_                                               | `channels.imessage.dbPath`                | Optional Messages.app `chat.db` override; auto-detected when omitted.                                                                                                                                                                                                                                                                        |
-| _(implicit)_                                               | `channels.imessage.remoteHost`            | `host` or `user@host` — only needed when `cliPath` is an SSH wrapper and you want SCP attachment fetches.                                                                                                                                                                                                                                    |
-| `channels.bluebubbles.dmPolicy`                            | `channels.imessage.dmPolicy`              | Same values (`pairing` / `allowlist` / `open` / `disabled`).                                                                                                                                                                                                                                                                                 |
-| `channels.bluebubbles.allowFrom`                           | `channels.imessage.allowFrom`             | Pairing approvals carry over by handle, not by token.                                                                                                                                                                                                                                                                                        |
-| `channels.bluebubbles.groupPolicy`                         | `channels.imessage.groupPolicy`           | Same values (`allowlist` / `open` / `disabled`).                                                                                                                                                                                                                                                                                             |
-| `channels.bluebubbles.groupAllowFrom`                      | `channels.imessage.groupAllowFrom`        | Same.                                                                                                                                                                                                                                                                                                                                        |
-| `channels.bluebubbles.groups`                              | `channels.imessage.groups`                | **Copy this verbatim, including any `groups: { "*": { ... } }` wildcard entry.** Per-group `requireMention`, `tools`, `toolsBySender` carry over. With `groupPolicy: "allowlist"`, an empty or missing `groups` block silently drops every group message — see "Group registry footgun" below.                                               |
-| `channels.bluebubbles.sendReadReceipts`                    | `channels.imessage.sendReadReceipts`      | Default `true`. With the bundled plugin this only fires when the private API probe is up.                                                                                                                                                                                                                                                    |
-| `channels.bluebubbles.includeAttachments`                  | `channels.imessage.includeAttachments`    | Same shape, **same off-by-default**. If you had attachments flowing on BlueBubbles you must re-set this explicitly on the iMessage block — it does not carry over implicitly, and inbound photos/media will be silently dropped with no `Inbound message` log line until you do.                                                             |
-| `channels.bluebubbles.attachmentRoots`                     | `channels.imessage.attachmentRoots`       | Local roots; same wildcard rules.                                                                                                                                                                                                                                                                                                            |
-| _(N/A)_                                                    | `channels.imessage.remoteAttachmentRoots` | Only used when `remoteHost` is set for SCP fetches.                                                                                                                                                                                                                                                                                          |
-| `channels.bluebubbles.mediaMaxMb`                          | `channels.imessage.mediaMaxMb`            | Default 16 MB on iMessage (BlueBubbles default was 8 MB). Set explicitly if you want to keep the lower cap.                                                                                                                                                                                                                                  |
-| `channels.bluebubbles.textChunkLimit`                      | `channels.imessage.textChunkLimit`        | Default 4000 on both.                                                                                                                                                                                                                                                                                                                        |
-| `channels.bluebubbles.coalesceSameSenderDms`               | `channels.imessage.coalesceSameSenderDms` | Same opt-in. DM-only — group chats keep instant per-message dispatch on both channels. Widens the default inbound debounce to 2500 ms when enabled without an explicit `messages.inbound.byChannel.imessage`. See [iMessage docs § Coalescing split-send DMs](/channels/imessage#coalescing-split-send-dms-command--url-in-one-composition). |
-| `channels.bluebubbles.enrichGroupParticipantsFromContacts` | _(N/A)_                                   | iMessage already reads sender display names from `chat.db`.                                                                                                                                                                                                                                                                                  |
-| `channels.bluebubbles.actions.*`                           | `channels.imessage.actions.*`             | Per-action toggles: `reactions`, `edit`, `unsend`, `reply`, `sendWithEffect`, `renameGroup`, `setGroupIcon`, `addParticipant`, `removeParticipant`, `leaveGroup`, `sendAttachment`.                                                                                                                                                          |
+| BlueBubbles                                                | bundled iMessage                          | Notes                                                                                                                                                                                                                                                                                                                                                                                |
+| ---------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `channels.bluebubbles.enabled`                             | `channels.imessage.enabled`               | Same semantics.                                                                                                                                                                                                                                                                                                                                                                      |
+| `channels.bluebubbles.serverUrl`                           | _(removed)_                               | No REST server — the plugin spawns `imsg rpc` over stdio.                                                                                                                                                                                                                                                                                                                            |
+| `channels.bluebubbles.password`                            | _(removed)_                               | No webhook authentication needed.                                                                                                                                                                                                                                                                                                                                                    |
+| _(implicit)_                                               | `channels.imessage.cliPath`               | Path to `imsg` (default `imsg`); use a wrapper script for SSH.                                                                                                                                                                                                                                                                                                                       |
+| _(implicit)_                                               | `channels.imessage.dbPath`                | Optional Messages.app `chat.db` override; auto-detected when omitted.                                                                                                                                                                                                                                                                                                                |
+| _(implicit)_                                               | `channels.imessage.remoteHost`            | `host` or `user@host` — only needed when `cliPath` is an SSH wrapper and you want SCP attachment fetches.                                                                                                                                                                                                                                                                            |
+| `channels.bluebubbles.dmPolicy`                            | `channels.imessage.dmPolicy`              | Same values (`pairing` / `allowlist` / `open` / `disabled`).                                                                                                                                                                                                                                                                                                                         |
+| `channels.bluebubbles.allowFrom`                           | `channels.imessage.allowFrom`             | Pairing approvals carry over by handle, not by token.                                                                                                                                                                                                                                                                                                                                |
+| `channels.bluebubbles.groupPolicy`                         | `channels.imessage.groupPolicy`           | Same values (`allowlist` / `open` / `disabled`).                                                                                                                                                                                                                                                                                                                                     |
+| `channels.bluebubbles.groupAllowFrom`                      | `channels.imessage.groupAllowFrom`        | Same.                                                                                                                                                                                                                                                                                                                                                                                |
+| `channels.bluebubbles.groups`                              | `channels.imessage.groups`                | **Copy this verbatim, including any `groups: { "*": { ... } }` wildcard entry.** Per-group `requireMention`, `tools`, `toolsBySender` carry over. With `groupPolicy: "allowlist"`, an empty or missing `groups` block silently drops every group message — see "Group registry footgun" below.                                                                                       |
+| `channels.bluebubbles.sendReadReceipts`                    | `channels.imessage.sendReadReceipts`      | Default `true`. With the bundled plugin this only fires when the private API probe is up.                                                                                                                                                                                                                                                                                            |
+| `channels.bluebubbles.includeAttachments`                  | `channels.imessage.includeAttachments`    | Same shape, **same off-by-default**. If you had attachments flowing on BlueBubbles you must re-set this explicitly on the iMessage block — it does not carry over implicitly, and inbound photos/media will be silently dropped with no `Inbound message` log line until you do.                                                                                                     |
+| `channels.bluebubbles.attachmentRoots`                     | `channels.imessage.attachmentRoots`       | Local roots; same wildcard rules.                                                                                                                                                                                                                                                                                                                                                    |
+| _(N/A)_                                                    | `channels.imessage.remoteAttachmentRoots` | Only used when `remoteHost` is set for SCP fetches.                                                                                                                                                                                                                                                                                                                                  |
+| `channels.bluebubbles.mediaMaxMb`                          | `channels.imessage.mediaMaxMb`            | Default 16 MB on iMessage (BlueBubbles default was 8 MB). Set explicitly if you want to keep the lower cap.                                                                                                                                                                                                                                                                          |
+| `channels.bluebubbles.textChunkLimit`                      | `channels.imessage.textChunkLimit`        | Default 4000 on both.                                                                                                                                                                                                                                                                                                                                                                |
+| `channels.bluebubbles.coalesceSameSenderDms`               | `channels.imessage.coalesceSameSenderDms` | Same opt-in. DM-only — group chats keep instant per-message dispatch on both channels. Widens the default inbound debounce to 7000 ms when enabled without an explicit `messages.inbound.byChannel.imessage` or global `messages.inbound.debounceMs`. See [iMessage docs § Coalescing split-send DMs](/channels/imessage#coalescing-split-send-dms-command--url-in-one-composition). |
+| `channels.bluebubbles.enrichGroupParticipantsFromContacts` | _(N/A)_                                   | iMessage already reads sender display names from `chat.db`.                                                                                                                                                                                                                                                                                                                          |
+| `channels.bluebubbles.actions.*`                           | `channels.imessage.actions.*`             | Per-action toggles: `reactions`, `edit`, `unsend`, `reply`, `sendWithEffect`, `renameGroup`, `setGroupIcon`, `addParticipant`, `removeParticipant`, `leaveGroup`, `sendAttachment`.                                                                                                                                                                                                  |
 
 Multi-account configs (`channels.bluebubbles.accounts.*`) translate one-to-one to `channels.imessage.accounts.*`.
 

docs/channels/imessage.md

@@ -681,7 +681,7 @@ The two rows arrive at OpenClaw ~0.8-2.0 s apart on most setups. Without coalesc
     }
     ```
 
-    With the flag on and no explicit `messages.inbound.byChannel.imessage`, the debounce window widens to **2500 ms** (the legacy default is 0 ms — no debouncing). The wider window is required because Apple's split-send cadence of 0.8-2.0 s does not fit in a tighter default.
+    With the flag on and no explicit `messages.inbound.byChannel.imessage` or global `messages.inbound.debounceMs`, the debounce window widens to **7000 ms** (the legacy default is 0 ms — no debouncing). The wider window is required because Apple's URL-preview split-send cadence can stretch to several seconds while Messages.app emits the preview row.
 
     To tune the window yourself:
 
@@ -690,10 +690,8 @@ The two rows arrive at OpenClaw ~0.8-2.0 s apart on most setups. Without coalesc
       messages: {
         inbound: {
           byChannel: {
-            // 2500 ms works for most setups; raise to 4000 ms if your Mac is
-            // slow or under memory pressure (observed gap can stretch past 2 s
-            // then).
-            imessage: 2500,
+            // 7000 ms covers observed Messages.app URL-preview delays.
+            imessage: 7000,
           },
         },
       },
@@ -715,15 +713,15 @@ The two rows arrive at OpenClaw ~0.8-2.0 s apart on most setups. Without coalesc
 
 The "Flag on" column shows behavior on an `imsg` build that emits `balloon_bundle_id`. On older `imsg` builds that emit no balloon metadata at all, the rows below marked "Two turns" / "N turns" instead fall back to a legacy merge (one turn): OpenClaw cannot structurally tell a split-send from separate sends, so it preserves the pre-metadata merge. Precise separation activates once the build emits balloon metadata.
 
-| User composes                                                      | `chat.db` produces                  | Flag off (default)                      | Flag on + window (imsg emits balloon metadata)   |
-| ------------------------------------------------------------------ | ----------------------------------- | --------------------------------------- | ------------------------------------------------ |
-| `Dump https://example.com` (one send)                              | 2 rows ~1 s apart                   | Two agent turns: "Dump" alone, then URL | One turn: merged text `Dump https://example.com` |
-| `Save this 📎image.jpg caption` (attachment + text)                | 2 rows without URL balloon metadata | Two turns                               | Two turns (legacy merge on metadata-less builds) |
-| `/status` (standalone command)                                     | 1 row                               | Instant dispatch                        | **Wait up to window, then dispatch**             |
-| URL pasted alone                                                   | 1 row                               | Instant dispatch                        | Wait up to window, then dispatch                 |
-| Text + URL sent as two deliberate separate messages, minutes apart | 2 rows outside window               | Two turns                               | Two turns (window expires between them)          |
-| Rapid flood (>10 small DMs inside window)                          | N rows without URL balloon metadata | N turns                                 | N turns (legacy merge on metadata-less builds)   |
-| Two people typing in a group chat                                  | N rows from M senders               | M+ turns (one per sender bucket)        | M+ turns — group chats are not coalesced         |
+| User composes                                                      | `chat.db` produces                  | Flag off (default)                      | Flag on + window (imsg emits balloon metadata)                                                      |
+| ------------------------------------------------------------------ | ----------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `Dump https://example.com` (one send)                              | 2 rows ~1 s apart                   | Two agent turns: "Dump" alone, then URL | One turn: merged text `Dump https://example.com`                                                    |
+| `Save this 📎image.jpg caption` (attachment + text)                | 2 rows without URL balloon metadata | Two turns                               | Two turns after metadata is observed; one merged turn on old/pre-latch metadata-less sessions       |
+| `/status` (standalone command)                                     | 1 row                               | Instant dispatch                        | **Wait up to window, then dispatch**                                                                |
+| URL pasted alone                                                   | 1 row                               | Instant dispatch                        | Wait up to window, then dispatch                                                                    |
+| Text + URL sent as two deliberate separate messages, minutes apart | 2 rows outside window               | Two turns                               | Two turns (window expires between them)                                                             |
+| Rapid flood (>10 small DMs inside window)                          | N rows without URL balloon metadata | N turns                                 | N turns after metadata is observed; one bounded merged turn on old/pre-latch metadata-less sessions |
+| Two people typing in a group chat                                  | N rows from M senders               | M+ turns (one per sender bucket)        | M+ turns — group chats are not coalesced                                                            |
 
 ## Inbound recovery after a bridge or gateway restart
 

docs/channels/index.md

@@ -39,9 +39,10 @@ Text is supported everywhere; media and reactions vary by channel.
 - [Nextcloud Talk](/channels/nextcloud-talk) - Self-hosted chat via Nextcloud Talk (bundled plugin).
 - [Nostr](/channels/nostr) - Decentralized DMs via NIP-04 (bundled plugin).
 - [QQ Bot](/channels/qqbot) - QQ Bot API; private chat, group chat, and rich media (bundled plugin).
+- [Raft](/channels/raft) - Raft CLI wake bridge for human and agent collaboration (external plugin).
 - [Signal](/channels/signal) - signal-cli; privacy-focused.
 - [Slack](/channels/slack) - Bolt SDK; workspace apps.
-- [SMS](/channels/sms) - Twilio-backed SMS through the Gateway webhook (bundled plugin).
+- [SMS](/channels/sms) - Twilio-backed SMS through the Gateway webhook (official plugin).
 - [Synology Chat](/channels/synology-chat) - Synology NAS Chat via outgoing+incoming webhooks (bundled plugin).
 - [Telegram](/channels/telegram) - Bot API via grammY; supports groups.
 - [Tlon](/channels/tlon) - Urbit-based messenger (bundled plugin).

docs/channels/irc.md

@@ -7,12 +7,18 @@ read_when:
 ---
 
 Use IRC when you want OpenClaw in classic channels (`#room`) and direct messages.
-IRC ships as a bundled plugin, but it is configured in the main config under `channels.irc`.
+Install the official IRC plugin, then configure it under `channels.irc`.
 
 ## Quick start
 
-1. Enable IRC config in `~/.openclaw/openclaw.json`.
-2. Set at least:
+1. Install the plugin:
+
+```bash
+openclaw plugins install @openclaw/irc
+```
+
+2. Enable IRC config in `~/.openclaw/openclaw.json`.
+3. Set at least:
 
 ```json5
 {
@@ -31,7 +37,7 @@ IRC ships as a bundled plugin, but it is configured in the main config under `ch
 
 Prefer a private IRC server for bot coordination. If you intentionally use a public IRC network, common choices include Libera.Chat, OFTC, and Snoonet. Avoid predictable public channels for bot or swarm backchannel traffic.
 
-3. Start/restart gateway:
+4. Start/restart gateway:
 
 ```bash
 openclaw gateway run

docs/channels/matrix.md

@@ -389,7 +389,7 @@ If the homeserver requires UIA to upload cross-signing keys, OpenClaw tries no-a
 Useful flags:
 
 - `--recovery-key-stdin` (pair with `printf '%s\n' "$MATRIX_RECOVERY_KEY" | …`) or `--recovery-key <key>`
-- `--force-reset-cross-signing` to discard the current cross-signing identity (intentional only)
+- `--force-reset-cross-signing` to discard the current cross-signing identity (intentional only; requires the active recovery key to be stored or supplied with `--recovery-key-stdin`)
 
 ### Room-key backup
 

docs/channels/mattermost.md

@@ -32,7 +32,7 @@ Details: [Plugins](/tools/plugin)
 
 <Steps>
   <Step title="Ensure plugin is available">
-    Current packaged OpenClaw releases already bundle it. Older/custom installs can add it manually with the commands above.
+    Install `@openclaw/mattermost` with the command above, then restart the Gateway if it is already running.
   </Step>
   <Step title="Create a Mattermost bot">
     Create a Mattermost bot account and copy the **bot token**.

docs/channels/raft.md

@@ -0,0 +1,147 @@
+---
+summary: "Raft External Agent support through the Raft CLI wake bridge"
+read_when:
+  - You want to connect OpenClaw to a Raft workspace
+  - You are configuring a Raft External Agent
+  - You are debugging Raft wake delivery
+title: "Raft"
+sidebarTitle: "Raft"
+---
+
+Raft support connects an OpenClaw agent to a Raft External Agent through the local
+Raft CLI. Raft sends authenticated wake hints to the Gateway. The agent then uses
+the Raft CLI to check and send messages.
+
+## Install
+
+Raft is an official external plugin. Install it on the Gateway host:
+
+```bash
+openclaw plugins install @openclaw/raft
+openclaw gateway restart
+```
+
+Details: [Plugins](/tools/plugin)
+
+## Prerequisites
+
+- A Raft workspace with an External Agent.
+- The Raft CLI installed on the same host as the OpenClaw Gateway.
+- A Raft CLI profile that is already signed in and associated with that External Agent.
+
+The plugin does not store Raft credentials. The Raft CLI keeps that authentication
+in its own profile.
+
+## Configure
+
+Set the profile in config:
+
+```json5
+{
+  channels: {
+    raft: {
+      enabled: true,
+      profile: "openclaw",
+    },
+  },
+}
+```
+
+For the default account, you can instead set `RAFT_PROFILE` in the Gateway
+environment:
+
+```bash
+RAFT_PROFILE=openclaw
+```
+
+Use a named account when one Gateway connects to more than one Raft External Agent:
+
+```json5
+{
+  channels: {
+    raft: {
+      accounts: {
+        support: {
+          profile: "support-agent",
+        },
+        engineering: {
+          profile: "engineering-agent",
+        },
+      },
+    },
+  },
+}
+```
+
+The interactive setup flow records the same profile:
+
+```bash
+openclaw channels setup raft
+```
+
+## How It Works
+
+When the Gateway starts, the plugin:
+
+1. Opens a loopback-only HTTP wake endpoint on an ephemeral port.
+2. Starts `raft --profile <profile> agent bridge` with that endpoint and a
+   per-process token.
+3. Accepts only authenticated, content-free wake hints with a replay identity from the local bridge.
+4. Requires one of `eventId`, `attemptId`, `messageId`, `delivery_id`, `wake_id`, or `id`.
+5. Deduplicates recent retried wake deliveries by bridge event id, including across Gateway restarts.
+6. Returns a stable runtime session for the current bridge and an empty activity-drain batch for the Raft CLI protocol.
+7. Starts one serialized OpenClaw agent turn for each accepted wake.
+
+The bridge owns Raft delivery retries and reconnects. The OpenClaw turn receives
+only a wake notice, not a copied Raft message body. It uses the CLI to read
+pending messages and to send its response:
+
+```bash
+raft --profile openclaw message check
+raft --profile openclaw message send
+```
+
+<Note>
+Raft is not a normal push-message transport. OpenClaw does not automatically
+send the model's final text back through the bridge, so the agent must use the
+Raft CLI after processing a wake.
+</Note>
+
+## Verify
+
+Check that OpenClaw can find the CLI and has a configured profile:
+
+```bash
+openclaw channels status --probe
+openclaw plugins inspect raft --runtime --json
+```
+
+Then send a message to the Raft External Agent. The Gateway log should show the
+Raft bridge starting, followed by an inbound wake. The agent should use the
+configured Raft profile to check its pending messages.
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Raft CLI is missing">
+    Install the Raft CLI on the Gateway host and make `raft` available on the
+    service's `PATH`. Verify it with `raft --help`, then restart the Gateway.
+  </Accordion>
+  <Accordion title="The bridge exits immediately">
+    Verify the configured profile is signed in and belongs to the intended
+    Raft External Agent. Run `raft --profile <profile> agent bridge` directly
+    to see the CLI diagnostic.
+  </Accordion>
+  <Accordion title="A wake arrives but no Raft response is sent">
+    This is expected when the agent does not invoke the Raft CLI. The wake
+    bridge does not carry message bodies or automatic final replies. Check the
+    agent's tool policy and ensure it can run `raft --profile <profile> message
+    check` and `message send`.
+  </Accordion>
+</AccordionGroup>
+
+## References
+
+- [Raft](https://raft.build/)
+- [Raft documentation](https://docs.raft.build/welcome/)
+- [Hermes Raft integration](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/raft)

docs/channels/signal.md

@@ -20,12 +20,18 @@ Status: external CLI integration. Gateway talks to `signal-cli` over HTTP — ei
 ## Quick setup (beginner)
 
 1. Use a **separate Signal number** for the bot (recommended).
-2. Install `signal-cli` (Java required if you use the JVM build).
-3. Choose one setup path:
+2. Install the OpenClaw plugin:
+
+```bash
+openclaw plugins install @openclaw/signal
+```
+
+3. Install `signal-cli` (Java required if you use the JVM build).
+4. Choose one setup path:
    - **Path A (QR link):** `signal-cli link -n "OpenClaw"` and scan with Signal.
    - **Path B (SMS register):** register a dedicated number with captcha + SMS verification.
-4. Configure OpenClaw and restart the gateway.
-5. Send a first DM and approve pairing (`openclaw pairing approve signal <CODE>`).
+5. Configure OpenClaw and restart the gateway.
+6. Send a first DM and approve pairing (`openclaw pairing approve signal <CODE>`).
 
 Minimal config:
 

docs/channels/sms.md

@@ -24,6 +24,7 @@ OpenClaw can receive and send SMS through a Twilio phone number or Messaging Ser
 
 You need:
 
+- The official SMS plugin installed with `openclaw plugins install @openclaw/sms`.
 - A Twilio account with an SMS-capable phone number, or a Twilio Messaging Service.
 - The Twilio Account SID and Auth Token.
 - A public HTTPS URL that reaches your OpenClaw Gateway.
@@ -34,6 +35,11 @@ Use one Twilio number for both SMS and Voice Call if the number has both capabil
 ## Quick Setup
 
 <Steps>
+  <Step title="Install the plugin">
+    ```bash
+    openclaw plugins install @openclaw/sms
+    ```
+  </Step>
   <Step title="Create or choose a Twilio sender">
     In Twilio, open **Phone Numbers > Manage > Active numbers** and choose an SMS-capable number. Save:
 

docs/ci.md

@@ -8,38 +8,51 @@ read_when:
   - You are changing ClawSweeper dispatch or GitHub activity forwarding
 ---
 
-OpenClaw CI runs on every push to `main` and every pull request. The `preflight` job classifies the diff and turns expensive lanes off when only unrelated areas changed. Manual `workflow_dispatch` runs intentionally bypass smart scoping and fan out the full graph for release candidates and broad validation. Android lanes stay opt-in through `include_android`. Release-only plugin coverage lives in the separate [`Plugin Prerelease`](#plugin-prerelease) workflow and only runs from [`Full Release Validation`](#full-release-validation) or an explicit manual dispatch.
+OpenClaw CI runs on every push to `main` and every pull request. Canonical
+`main` pushes first pass through a 90-second hosted-runner admission window.
+The existing `CI` concurrency group cancels that waiting run when a newer
+commit lands, so sequential merges do not each register a full Blacksmith
+matrix. Pull requests and manual dispatches skip the wait. The `preflight` job
+then classifies the diff and turns expensive lanes off when only unrelated
+areas changed. Manual `workflow_dispatch` runs intentionally bypass smart
+scoping and fan out the full graph for release candidates and broad
+validation. Android lanes stay opt-in through `include_android`. Release-only
+plugin coverage lives in the separate [`Plugin Prerelease`](#plugin-prerelease)
+workflow and only runs from [`Full Release Validation`](#full-release-validation)
+or an explicit manual dispatch.
 
 ## Pipeline overview
 
-| Job                                | Purpose                                                                                                   | When it runs                       |
-| ---------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------- |
-| `preflight`                        | Detect docs-only changes, changed scopes, changed extensions, and build the CI manifest                   | Always on non-draft pushes and PRs |
-| `security-fast`                    | Private key detection, changed-workflow audit via `zizmor`, and production lockfile audit                 | Always on non-draft pushes and PRs |
-| `check-dependencies`               | Production Knip dependency-only pass plus the unused-file allowlist guard                                 | Node-relevant changes              |
-| `build-artifacts`                  | Build `dist/`, Control UI, built-CLI smoke checks, embedded built-artifact checks, and reusable artifacts | Node-relevant changes              |
-| `checks-fast-core`                 | Fast Linux correctness lanes such as bundled, protocol, and CI-routing checks                             | Node-relevant changes              |
-| `checks-fast-contracts-plugins-*`  | Two sharded plugin contract checks                                                                        | Node-relevant changes              |
-| `checks-fast-contracts-channels-*` | Two sharded channel contract checks                                                                       | Node-relevant changes              |
-| `checks-node-core-*`               | Core Node test shards, excluding channel, bundled, contract, and extension lanes                          | Node-relevant changes              |
-| `check-*`                          | Sharded main local gate equivalent: prod types, lint, guards, test types, and strict smoke                | Node-relevant changes              |
-| `check-additional-*`               | Architecture, sharded boundary/prompt drift, extension guards, package boundary, and runtime topology     | Node-relevant changes              |
-| `checks-node-compat-node22`        | Node 22 compatibility build and smoke lane                                                                | Manual CI dispatch for releases    |
-| `check-docs`                       | Docs formatting, lint, and broken-link checks                                                             | Docs changed                       |
-| `skills-python`                    | Ruff + pytest for Python-backed skills                                                                    | Python-skill-relevant changes      |
-| `checks-windows`                   | Windows-specific process/path tests plus shared runtime import specifier regressions                      | Windows-relevant changes           |
-| `macos-node`                       | macOS TypeScript test lane using the shared built artifacts                                               | macOS-relevant changes             |
-| `macos-swift`                      | Swift lint, build, and tests for the macOS app                                                            | macOS-relevant changes             |
-| `android`                          | Android unit tests for both flavors plus one debug APK build                                              | Android-relevant changes           |
-| `test-performance-agent`           | Daily Codex slow-test optimization after trusted activity                                                 | Main CI success or manual dispatch |
-| `openclaw-performance`             | Daily/on-demand Kova runtime performance reports with mock-provider, deep-profile, and GPT 5.5 live lanes | Scheduled and manual dispatch      |
+| Job                                | Purpose                                                                                                   | When it runs                                        |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `preflight`                        | Detect docs-only changes, changed scopes, changed extensions, and build the CI manifest                   | Always on non-draft pushes and PRs                  |
+| `runner-admission`                 | Hosted 90-second debounce for canonical `main` pushes before Blacksmith work is registered                | Every CI run; sleep only on canonical `main` pushes |
+| `security-fast`                    | Private key detection, changed-workflow audit via `zizmor`, and production lockfile audit                 | Always on non-draft pushes and PRs                  |
+| `check-dependencies`               | Production Knip dependency-only pass plus the unused-file allowlist guard                                 | Node-relevant changes                               |
+| `build-artifacts`                  | Build `dist/`, Control UI, built-CLI smoke checks, embedded built-artifact checks, and reusable artifacts | Node-relevant changes                               |
+| `checks-fast-core`                 | Fast Linux correctness lanes such as bundled, protocol, and CI-routing checks                             | Node-relevant changes                               |
+| `checks-fast-contracts-plugins-*`  | Two sharded plugin contract checks                                                                        | Node-relevant changes                               |
+| `checks-fast-contracts-channels-*` | Two sharded channel contract checks                                                                       | Node-relevant changes                               |
+| `checks-node-core-*`               | Core Node test shards, excluding channel, bundled, contract, and extension lanes                          | Node-relevant changes                               |
+| `check-*`                          | Sharded main local gate equivalent: prod types, lint, guards, test types, and strict smoke                | Node-relevant changes                               |
+| `check-additional-*`               | Architecture, sharded boundary/prompt drift, extension guards, package boundary, and runtime topology     | Node-relevant changes                               |
+| `checks-node-compat-node22`        | Node 22 compatibility build and smoke lane                                                                | Manual CI dispatch for releases                     |
+| `check-docs`                       | Docs formatting, lint, and broken-link checks                                                             | Docs changed                                        |
+| `skills-python`                    | Ruff + pytest for Python-backed skills                                                                    | Python-skill-relevant changes                       |
+| `checks-windows`                   | Windows-specific process/path tests plus shared runtime import specifier regressions                      | Windows-relevant changes                            |
+| `macos-node`                       | macOS TypeScript test lane using the shared built artifacts                                               | macOS-relevant changes                              |
+| `macos-swift`                      | Swift lint, build, and tests for the macOS app                                                            | macOS-relevant changes                              |
+| `android`                          | Android unit tests for both flavors plus one debug APK build                                              | Android-relevant changes                            |
+| `test-performance-agent`           | Daily Codex slow-test optimization after trusted activity                                                 | Main CI success or manual dispatch                  |
+| `openclaw-performance`             | Daily/on-demand Kova runtime performance reports with mock-provider, deep-profile, and GPT 5.5 live lanes | Scheduled and manual dispatch                       |
 
 ## Fail-fast order
 
-1. `preflight` decides which lanes exist at all. The `docs-scope` and `changed-scope` logic are steps inside this job, not standalone jobs.
-2. `security-fast`, `check-*`, `check-additional-*`, `check-docs`, and `skills-python` fail quickly without waiting on the heavier artifact and platform matrix jobs.
-3. `build-artifacts` overlaps with the fast Linux lanes so downstream consumers can start as soon as the shared build is ready.
-4. Heavier platform and runtime lanes fan out after that: `checks-fast-core`, `checks-fast-contracts-plugins-*`, `checks-fast-contracts-channels-*`, `checks-node-core-*`, `checks-windows`, `macos-node`, `macos-swift`, and `android`.
+1. `runner-admission` waits only for canonical `main` pushes; a newer push cancels the run before Blacksmith registration.
+2. `preflight` decides which lanes exist at all. The `docs-scope` and `changed-scope` logic are steps inside this job, not standalone jobs.
+3. `security-fast`, `check-*`, `check-additional-*`, `check-docs`, and `skills-python` fail quickly without waiting on the heavier artifact and platform matrix jobs.
+4. `build-artifacts` overlaps with the fast Linux lanes so downstream consumers can start as soon as the shared build is ready.
+5. Heavier platform and runtime lanes fan out after that: `checks-fast-core`, `checks-fast-contracts-plugins-*`, `checks-fast-contracts-channels-*`, `checks-node-core-*`, `checks-windows`, `macos-node`, `macos-swift`, and `android`.
 
 GitHub may mark superseded jobs as `cancelled` when a newer push lands on the same PR or `main` ref. Treat that as CI noise unless the newest run for the same ref is also failing. Matrix jobs use `fail-fast: false`, and `build-artifacts` reports embedded channel, core-support-boundary, and gateway-watch failures directly instead of queuing tiny verifier jobs. The automatic CI concurrency key is versioned (`CI-v7-*`) so a GitHub-side zombie in an old queue group cannot indefinitely block newer main runs. Manual full-suite runs use `CI-manual-v1-*` and do not cancel in-progress runs.
 
@@ -74,7 +87,15 @@ Scope logic lives in `scripts/ci-changed-scope.mjs` and is covered by unit tests
 - **CI routing-only edits, selected cheap core-test fixture edits, and narrow plugin contract helper/test-routing edits** use a fast Node-only manifest path: `preflight`, security, and a single `checks-fast-core` task. That path skips build artifacts, Node 22 compatibility, channel contracts, full core shards, bundled-plugin shards, and additional guard matrices when the change is limited to the routing or helper surfaces the fast task exercises directly.
 - **Windows Node checks** are scoped to Windows-specific process/path wrappers, npm/pnpm/UI runner helpers, package manager config, and the CI workflow surfaces that execute that lane; unrelated source, plugin, install-smoke, and test-only changes stay on the Linux Node lanes.
 
-The slowest Node test families are split or balanced so each job stays small without over-reserving runners: plugin contracts and channel contracts each run as two weighted Blacksmith-backed shards with the standard GitHub runner fallback, core unit fast/support lanes run separately, core runtime infra is split between state, process/config, shared, and three cron domain shards, auto-reply runs as balanced workers (with the reply subtree split into agent-runner, dispatch, and commands/state-routing shards), and agentic gateway/server configs are split across chat/auth/model/http-plugin/runtime/startup lanes instead of waiting on built artifacts. Broad browser, QA, media, and miscellaneous plugin tests use their dedicated Vitest configs instead of the shared plugin catch-all. Include-pattern shards record timing entries using the CI shard name, so `.artifacts/vitest-shard-timings.json` can distinguish a whole config from a filtered shard. `check-additional-*` keeps package-boundary compile/canary work together and separates runtime topology architecture from gateway watch coverage; the boundary guard list is striped into one prompt-heavy shard and one combined shard for the remaining guard stripes, each running selected independent guards concurrently and printing per-check timings. The expensive Codex happy-path prompt snapshot drift check runs as its own additional job for manual CI and for prompt-affecting changes only, so normal unrelated Node changes do not wait behind cold prompt snapshot generation and the boundary shards stay balanced while prompt drift is still pinned to the PR that caused it; the same flag skips prompt snapshot Vitest generation inside the built-artifact core support-boundary shard. Gateway watch, channel tests, and the core support-boundary shard run concurrently inside `build-artifacts` after `dist/` and `dist-runtime/` are already built.
+The slowest Node test families are split or balanced so each job stays small without over-reserving runners: plugin contracts and channel contracts each run as two weighted Blacksmith-backed shards with the standard GitHub runner fallback, core unit fast/support lanes run separately, core runtime infra is split between state, process/config, shared, and three cron domain shards, auto-reply runs as balanced workers (with the reply subtree split into agent-runner, dispatch, and commands/state-routing shards), and agentic gateway/server configs are split across chat/auth/model/http-plugin/runtime/startup lanes instead of waiting on built artifacts. Normal CI then packs only isolated infra include-pattern shards into deterministic bundles of at most 64 test files, reducing the Node matrix without merging non-isolated command/cron, stateful agents-core, or gateway/server suites; heavy fixed suites stay on 8 vCPU while the bundled and lower-weight lanes use 4 vCPU. Pull requests on the canonical repository use an additional compact admission plan: the same per-config groups run in isolated subprocesses inside the current 34-job Linux Node plan, so a single PR does not register the full 70-plus-job Node matrix. `main` pushes, manual dispatches, and release gates retain the full matrix. Broad browser, QA, media, and miscellaneous plugin tests use their dedicated Vitest configs instead of the shared plugin catch-all. Include-pattern shards record timing entries using the CI shard name, so `.artifacts/vitest-shard-timings.json` can distinguish a whole config from a filtered shard. `check-additional-*` keeps package-boundary compile/canary work together and separates runtime topology architecture from gateway watch coverage; the boundary guard list is striped into one prompt-heavy shard and one combined shard for the remaining guard stripes, each running selected independent guards concurrently and printing per-check timings. The expensive Codex happy-path prompt snapshot drift check runs as its own additional job for manual CI and for prompt-affecting changes only, so normal unrelated Node changes do not wait behind cold prompt snapshot generation and the boundary shards stay balanced while prompt drift is still pinned to the PR that caused it; the same flag skips prompt snapshot Vitest generation inside the built-artifact core support-boundary shard. Gateway watch, channel tests, and the core support-boundary shard run concurrently inside `build-artifacts` after `dist/` and `dist-runtime/` are already built.
+
+Once admitted, canonical Linux CI permits up to 12 concurrent Node jobs and 8 for
+the smaller fast/check lanes; Windows and Android stay at two because those
+runner pools are narrower.
+
+The compact PR plan emits 18 Node jobs for the current suite: whole-config
+groups are batched in isolated subprocesses with a 120-minute batch timeout,
+while include-pattern groups share the same bounded job budget.
 
 Android CI runs both `testPlayDebugUnitTest` and `testThirdPartyDebugUnitTest` and then builds the Play debug APK. The third-party flavor has no separate source set or manifest; its unit-test lane still compiles the flavor with the SMS/call-log BuildConfig flags, while avoiding a duplicate debug APK packaging job on every Android-relevant push.
 
@@ -111,15 +132,15 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
 
 ## Runners
 
-| Runner                           | Jobs                                                                                                                                                                                                                                |
-| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ubuntu-24.04`                   | Manual CI dispatch and non-canonical repository fallbacks, workflow-sanity, labeler, auto-response, docs workflows outside CI, and install-smoke preflight so the Blacksmith matrix can queue earlier                               |
-| `blacksmith-4vcpu-ubuntu-2404`   | `CodeQL Critical Quality`, `preflight`, `security-fast`, lower-weight extension shards, `checks-fast-core`, plugin/channel contract shards, `checks-node-compat-node22`, `check-guards`, `check-prod-types`, and `check-test-types` |
-| `blacksmith-8vcpu-ubuntu-2404`   | Linux Node test shards, bundled plugin test shards, `check-additional-*` shards, `check-dependencies`, and `android`                                                                                                                |
-| `blacksmith-16vcpu-ubuntu-2404`  | `build-artifacts`, `check-lint` (CPU-sensitive enough that 8 vCPU cost more than they saved); install-smoke Docker builds (32-vCPU queue time cost more than it saved)                                                              |
-| `blacksmith-16vcpu-windows-2025` | `checks-windows`                                                                                                                                                                                                                    |
-| `blacksmith-6vcpu-macos-15`      | `macos-node` on `openclaw/openclaw`; forks fall back to `macos-15`                                                                                                                                                                  |
-| `blacksmith-12vcpu-macos-26`     | `macos-swift` on `openclaw/openclaw`; forks fall back to `macos-26`                                                                                                                                                                 |
+| Runner                          | Jobs                                                                                                                                                                                                                                                                                                            |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ubuntu-24.04`                  | Manual CI dispatch and non-canonical repository fallbacks, workflow-sanity, labeler, auto-response, docs workflows outside CI, and install-smoke preflight so the Blacksmith matrix can queue earlier                                                                                                           |
+| `blacksmith-4vcpu-ubuntu-2404`  | `CodeQL Critical Quality`, `preflight`, `security-fast`, lower-weight extension shards, `checks-fast-core`, plugin/channel contract shards, most bundled/lower-weight Linux Node shards, `check-guards`, `check-prod-types`, `check-test-types`, selected `check-additional-*` shards, and `check-dependencies` |
+| `blacksmith-8vcpu-ubuntu-2404`  | Retained heavy Linux Node suites, boundary/extension-heavy `check-additional-*` shards, and `android`                                                                                                                                                                                                           |
+| `blacksmith-16vcpu-ubuntu-2404` | `build-artifacts`, `check-lint` (CPU-sensitive enough that 8 vCPU cost more than they saved); install-smoke Docker builds (32-vCPU queue time cost more than it saved)                                                                                                                                          |
+| `blacksmith-8vcpu-windows-2025` | `checks-windows`                                                                                                                                                                                                                                                                                                |
+| `blacksmith-6vcpu-macos-15`     | `macos-node` on `openclaw/openclaw`; forks fall back to `macos-15`                                                                                                                                                                                                                                              |
+| `blacksmith-12vcpu-macos-26`    | `macos-swift` on `openclaw/openclaw`; forks fall back to `macos-26`                                                                                                                                                                                                                                             |
 
 Canonical-repo CI keeps Blacksmith as the default runner path for normal push and pull-request runs. `workflow_dispatch` and non-canonical repository runs use GitHub-hosted runners, but normal canonical runs do not currently probe Blacksmith queue health or automatically fall back to GitHub-hosted labels when Blacksmith is unavailable.
 

docs/cli/cron.md

@@ -197,7 +197,7 @@ Isolated cron resolves the active model in this order:
 
 ### Fast mode
 
-Isolated cron fast mode follows the resolved live model selection. Model config `params.fastMode` applies by default, but a stored session `fastMode` override still wins over config.
+Isolated cron fast mode follows the resolved live model selection. Model config `params.fastMode` applies by default, but a stored session `fastMode` override still wins over config. When the resolved mode is `auto`, the cutoff uses the selected model's `params.fastAutoOnSeconds` value, defaulting to 60 seconds.
 
 ### Live model switch retries
 

docs/cli/gateway.md

@@ -165,10 +165,15 @@ When you set `--url`, the CLI does not fall back to config or environment creden
 
 ```bash
 openclaw gateway health --url ws://127.0.0.1:18789
+openclaw gateway health --port 18789
 ```
 
 The HTTP `/healthz` endpoint is a liveness probe: it returns once the server can answer HTTP. The HTTP `/readyz` endpoint is stricter and stays red while startup plugin sidecars, channels, or configured hooks are still settling. Local or authenticated detailed readiness responses include an `eventLoop` diagnostic block with event-loop delay, event-loop utilization, CPU core ratio, and a `degraded` flag.
 
+<ParamField path="--port <port>" type="number">
+  Target a local loopback Gateway on this port. This overrides `OPENCLAW_GATEWAY_URL` and `OPENCLAW_GATEWAY_PORT` for the health call.
+</ParamField>
+
 ### `gateway usage-cost`
 
 Fetch usage-cost summaries from session logs.
@@ -340,8 +345,13 @@ If multiple probe targets are reachable, it prints all of them. An SSH tunnel, T
 ```bash
 openclaw gateway probe
 openclaw gateway probe --json
+openclaw gateway probe --port 18789
 ```
 
+<ParamField path="--port <port>" type="number">
+  Use this port for the local loopback probe target and SSH tunnel remote port. Without `--url`, this selects the local loopback target instead of configured gateway environment URL, environment port, or remote targets.
+</ParamField>
+
 <AccordionGroup>
   <Accordion title="Interpretation">
     - `Reachable: yes` means at least one target accepted a WebSocket connect.

docs/concepts/model-providers.md

@@ -333,7 +333,7 @@ Gateway model capability checks also read explicit `models.providers.<id>.models
 
 ### Moonshot AI (Kimi)
 
-Moonshot ships as a bundled provider plugin. Use the built-in provider by default, and add an explicit `models.providers.moonshot` entry only when you need to override the base URL or model metadata:
+Install `@openclaw/moonshot-provider` before onboarding. Add an explicit `models.providers.moonshot` entry only when you need to override the base URL or model metadata:
 
 - Provider: `moonshot`
 - Auth: `MOONSHOT_API_KEY`

docs/docs.json

@@ -1122,6 +1122,7 @@
                   "channels/mattermost",
                   "channels/nextcloud-talk",
                   "channels/nostr",
+                  "channels/raft",
                   "channels/tlon",
                   "channels/synology-chat",
                   "channels/twitch"

docs/gateway/config-agents.md

@@ -1099,7 +1099,7 @@ for provider examples and precedence.
 - `skills`: optional per-agent skill allowlist. If omitted, the agent inherits `agents.defaults.skills` when set; an explicit list replaces defaults instead of merging, and `[]` means no skills.
 - `thinkingDefault`: optional per-agent default thinking level (`off | minimal | low | medium | high | xhigh | adaptive | max`). Overrides `agents.defaults.thinkingDefault` for this agent when no per-message or session override is set. The selected provider/model profile controls which values are valid; for Google Gemini, `adaptive` keeps provider-owned dynamic thinking (`thinkingLevel` omitted on Gemini 3/3.1, `thinkingBudget: -1` on Gemini 2.5).
 - `reasoningDefault`: optional per-agent default reasoning visibility (`on | off | stream`). Overrides `agents.defaults.reasoningDefault` for this agent when no per-message or session reasoning override is set.
-- `fastModeDefault`: optional per-agent default for fast mode (`true | false`). Applies when no per-message or session fast-mode override is set.
+- `fastModeDefault`: optional per-agent default for fast mode (`"auto" | true | false`). Applies when no per-message or session fast-mode override is set.
 - `models`: optional per-agent model catalog/runtime overrides keyed by full `provider/model` ids. Use `models["provider/model"].agentRuntime` for per-agent runtime exceptions.
 - `runtime`: optional per-agent runtime descriptor. Use `type: "acp"` with `runtime.acp` defaults (`agent`, `backend`, `mode`, `cwd`) when the agent should default to ACP harness sessions.
 - `identity.avatar`: workspace-relative path, `http(s)` URL, or `data:` URI.

docs/gateway/doctor.md

@@ -160,6 +160,7 @@ must be paired with `--lint`; regular doctor and repair runs reject them.
     - State integrity and permissions checks (sessions, transcripts, state dir).
     - Config file permission checks (chmod 600) when running locally.
     - Model auth health: checks OAuth expiry, can refresh expiring tokens, and reports auth-profile cooldown/disabled states.
+
   </Accordion>
   <Accordion title="Gateway, services, and supervisors">
     - Sandbox image repair when sandboxing is enabled.

docs/gateway/protocol.md

@@ -445,6 +445,7 @@ enumeration of `src/gateway/server-methods/*.ts`.
     - `sessions.get` returns the full stored session row.
     - Chat execution still uses `chat.history`, `chat.send`, `chat.abort`, and `chat.inject`. `chat.history` is display-normalized for UI clients: inline directive tags are stripped from visible text, plain-text tool-call XML payloads (including `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, and truncated tool-call blocks) and leaked ASCII/full-width model control tokens are stripped, pure silent-token assistant rows such as exact `NO_REPLY` / `no_reply` are omitted, and oversized rows can be replaced with placeholders.
     - `chat.message.get` is the additive bounded full-message reader for a single visible transcript entry. Clients pass `sessionKey`, optional `agentId` when the session selection is agent-scoped, plus a transcript `messageId` previously surfaced through `chat.history`, and the Gateway returns the same display-normalized projection without the lightweight history truncation cap when the stored entry is still available and not oversized.
+    - `chat.send` accepts one-turn `fastMode: "auto"` to use fast mode for model calls started before the auto cutoff, then start later retry, fallback, tool-result, or continuation calls without fast mode. The cutoff defaults to 60 seconds and can be configured per model with `agents.defaults.models["<provider>/<model>"].params.fastAutoOnSeconds`. A `chat.send` caller can pass one-turn `fastAutoOnSeconds` to override the cutoff for that request.
 
   </Accordion>
 

docs/help/faq-models.md

@@ -174,6 +174,7 @@ troubleshooting, see the main [FAQ](/help/faq).
 
     - **Per session:** send `/fast on` while the session is using `openai/gpt-5.5`.
     - **Per model default:** set `agents.defaults.models["openai/gpt-5.5"].params.fastMode` to `true`.
+    - **Automatic cutoff:** use `/fast auto` or `params.fastMode: "auto"` to start new model calls fast until the auto cutoff, then start later retry, fallback, tool-result, or continuation calls without fast mode. The cutoff defaults to 60 seconds; set `params.fastAutoOnSeconds` on the active model to change it.
 
     Example:
 
@@ -184,7 +185,8 @@ troubleshooting, see the main [FAQ](/help/faq).
           models: {
             "openai/gpt-5.5": {
               params: {
-                fastMode: true,
+                fastMode: "auto",
+                fastAutoOnSeconds: 30,
               },
             },
           },
@@ -193,7 +195,7 @@ troubleshooting, see the main [FAQ](/help/faq).
     }
     ```
 
-    For OpenAI, fast mode maps to `service_tier = "priority"` on supported native Responses requests. Session `/fast` overrides beat config defaults.
+    For OpenAI, fast mode maps to `service_tier = "priority"` on supported native Responses requests. Session `/fast` overrides beat config defaults. Codex app-server turns can only receive the tier at turn start, so `auto` applies on the next OpenClaw-started model turn rather than inside one already-running app-server turn.
 
     See [Thinking and fast mode](/tools/thinking) and [OpenAI fast mode](/providers/openai#fast-mode).
 

docs/plugins/building-plugins.md

@@ -145,11 +145,6 @@ local proof.
     Use `definePluginEntry` for non-channel plugins. Channel plugins use
     `defineChannelPluginEntry`.
 
-    Tool handlers may accept an optional fifth execution-context argument when
-    they need runtime-owned facts for the current call. The context includes the
-    active `runId`, effective `sessionKey`, ephemeral `sessionId`, owning
-    `agentId`, and ambient `deliveryContext` when those values are available.
-
   </Step>
 
   <Step title="Test the runtime">

docs/plugins/hooks.md

@@ -146,6 +146,7 @@ observation-only.
 - `subagent_delivery_target` - compatibility hook for completion delivery when no core session binding can project a route.
 - `subagent_spawning` - deprecated compatibility hook. Core now prepares `thread: true` subagent bindings through channel session-binding adapters before `subagent_spawned` fires.
 - `subagent_spawned` includes `resolvedModel` and `resolvedProvider` when OpenClaw has resolved the child session's native model before launch.
+- `subagent_ended` carries `targetSessionKey` (identity — this matches `subagent_spawned.childSessionKey`), `targetKind` (`"subagent"` or `"acp"`), `reason`, optional `outcome` (`"ok"`, `"error"`, `"timeout"`, `"killed"`, `"reset"`, or `"deleted"`), optional `error`, `runId`, `endedAt`, `accountId`, and `sendFarewell`. It does **not** include `agentId` or `childSessionKey`; use `targetSessionKey` to correlate with the corresponding `subagent_spawned` event.
 
 **Lifecycle**
 

docs/plugins/plugin-inventory.md

@@ -51,7 +51,7 @@ Each entry lists the package, distribution route, and description.
 
 ## Core npm package
 
-72 plugins
+59 plugins
 
 - **[admin-http-rpc](/plugins/reference/admin-http-rpc)** (`@openclaw/admin-http-rpc`) - included in OpenClaw. OpenClaw admin HTTP RPC endpoint.
 
@@ -69,8 +69,6 @@ Each entry lists the package, distribution route, and description.
 
 - **[canvas](/plugins/reference/canvas)** (`@openclaw/canvas-plugin`) - included in OpenClaw. Experimental Canvas control and A2UI rendering surfaces for paired nodes.
 
-- **[clickclack](/plugins/reference/clickclack)** (`@openclaw/clickclack`) - included in OpenClaw. Adds the Clickclack channel surface for sending and receiving OpenClaw messages.
-
 - **[codex-supervisor](/plugins/reference/codex-supervisor)** (`@openclaw/codex-supervisor`) - included in OpenClaw. Supervise Codex app-server sessions from OpenClaw.
 
 - **[cohere](/plugins/reference/cohere)** (`@openclaw/cohere-provider`) - included in OpenClaw; npm; ClawHub: `clawhub:@openclaw/cohere-provider`. OpenClaw Cohere provider plugin.
@@ -91,8 +89,6 @@ Each entry lists the package, distribution route, and description.
 
 - **[file-transfer](/plugins/reference/file-transfer)** (`@openclaw/file-transfer`) - included in OpenClaw. Fetch, list, and write files on paired nodes via dedicated node commands. Bypasses bash stdout truncation by using base64 over node.invoke for binaries up to 16 MB.
 
-- **[fireworks](/plugins/reference/fireworks)** (`@openclaw/fireworks-provider`) - included in OpenClaw. Adds Fireworks model provider support to OpenClaw.
-
 - **[github-copilot](/plugins/reference/github-copilot)** (`@openclaw/github-copilot-provider`) - included in OpenClaw. Adds GitHub Copilot model provider support to OpenClaw.
 
 - **[google](/plugins/reference/google)** (`@openclaw/google-plugin`) - included in OpenClaw. Adds Google, Google Gemini CLI, Google Vertex model provider support to OpenClaw.
@@ -101,16 +97,12 @@ Each entry lists the package, distribution route, and description.
 
 - **[imessage](/plugins/reference/imessage)** (`@openclaw/imessage`) - included in OpenClaw. Adds the iMessage channel surface for sending and receiving OpenClaw messages.
 
-- **[irc](/plugins/reference/irc)** (`@openclaw/irc`) - included in OpenClaw. Adds the IRC channel surface for sending and receiving OpenClaw messages.
-
 - **[litellm](/plugins/reference/litellm)** (`@openclaw/litellm-provider`) - included in OpenClaw. Adds LiteLLM model provider support to OpenClaw.
 
 - **[llm-task](/plugins/reference/llm-task)** (`@openclaw/llm-task`) - included in OpenClaw. Generic JSON-only LLM tool for structured tasks callable from workflows.
 
 - **[lmstudio](/plugins/reference/lmstudio)** (`@openclaw/lmstudio-provider`) - included in OpenClaw. Adds LM Studio model provider support to OpenClaw.
 
-- **[mattermost](/plugins/reference/mattermost)** (`@openclaw/mattermost`) - included in OpenClaw. Adds the Mattermost channel surface for sending and receiving OpenClaw messages.
-
 - **[memory-core](/plugins/reference/memory-core)** (`@openclaw/memory-core`) - included in OpenClaw. Adds agent-callable tools.
 
 - **[memory-wiki](/plugins/reference/memory-wiki)** (`@openclaw/memory-wiki`) - included in OpenClaw. Persistent wiki compiler and Obsidian-friendly knowledge vault for OpenClaw.
@@ -127,8 +119,6 @@ Each entry lists the package, distribution route, and description.
 
 - **[mistral](/plugins/reference/mistral)** (`@openclaw/mistral-provider`) - included in OpenClaw. Adds Mistral model provider support to OpenClaw.
 
-- **[moonshot](/plugins/reference/moonshot)** (`@openclaw/moonshot-provider`) - included in OpenClaw. Adds Moonshot model provider support to OpenClaw.
-
 - **[novita](/plugins/reference/novita)** (`@openclaw/novita-provider`) - included in OpenClaw. Adds Novita, Novita AI, Novitaai model provider support to OpenClaw.
 
 - **[nvidia](/plugins/reference/nvidia)** (`@openclaw/nvidia-provider`) - included in OpenClaw. Adds NVIDIA model provider support to OpenClaw.
@@ -151,32 +141,18 @@ Each entry lists the package, distribution route, and description.
 
 - **[runway](/plugins/reference/runway)** (`@openclaw/runway-provider`) - included in OpenClaw. Adds video generation provider support.
 
-- **[searxng](/plugins/reference/searxng)** (`@openclaw/searxng-plugin`) - included in OpenClaw. Adds web search provider support.
-
 - **[senseaudio](/plugins/reference/senseaudio)** (`@openclaw/senseaudio-provider`) - included in OpenClaw. Adds media understanding provider support.
 
 - **[sglang](/plugins/reference/sglang)** (`@openclaw/sglang-provider`) - included in OpenClaw. Adds SGLang model provider support to OpenClaw.
 
-- **[signal](/plugins/reference/signal)** (`@openclaw/signal`) - included in OpenClaw. Adds the Signal channel surface for sending and receiving OpenClaw messages.
-
-- **[sms](/plugins/reference/sms)** (`@openclaw/sms`) - included in OpenClaw. Twilio SMS channel plugin for OpenClaw text messages.
-
 - **[synthetic](/plugins/reference/synthetic)** (`@openclaw/synthetic-provider`) - included in OpenClaw. Adds Synthetic model provider support to OpenClaw.
 
-- **[tavily](/plugins/reference/tavily)** (`@openclaw/tavily-plugin`) - included in OpenClaw. Adds agent-callable tools. Adds web search provider support.
-
 - **[telegram](/plugins/reference/telegram)** (`@openclaw/telegram`) - included in OpenClaw. Adds the Telegram channel surface for sending and receiving OpenClaw messages.
 
-- **[tencent](/plugins/reference/tencent)** (`@openclaw/tencent-provider`) - included in OpenClaw. Adds Tencent TokenHub model provider support to OpenClaw.
-
 - **[together](/plugins/reference/together)** (`@openclaw/together-provider`) - included in OpenClaw. Adds Together model provider support to OpenClaw.
 
 - **[tts-local-cli](/plugins/reference/tts-local-cli)** (`@openclaw/tts-local-cli`) - included in OpenClaw. Adds text-to-speech provider support.
 
-- **[venice](/plugins/reference/venice)** (`@openclaw/venice-provider`) - included in OpenClaw. Adds Venice model provider support to OpenClaw.
-
-- **[vercel-ai-gateway](/plugins/reference/vercel-ai-gateway)** (`@openclaw/vercel-ai-gateway-provider`) - included in OpenClaw. Adds Vercel AI Gateway model provider support to OpenClaw.
-
 - **[vllm](/plugins/reference/vllm)** (`@openclaw/vllm-provider`) - included in OpenClaw. Adds vLLM model provider support to OpenClaw.
 
 - **[volcengine](/plugins/reference/volcengine)** (`@openclaw/volcengine-provider`) - included in OpenClaw. Adds Volcengine, Volcengine Plan model provider support to OpenClaw.
@@ -195,11 +171,9 @@ Each entry lists the package, distribution route, and description.
 
 - **[xiaomi](/plugins/reference/xiaomi)** (`@openclaw/xiaomi-provider`) - included in OpenClaw. Adds Xiaomi, Xiaomi Token Plan model provider support to OpenClaw.
 
-- **[zai](/plugins/reference/zai)** (`@openclaw/zai-provider`) - included in OpenClaw. Adds Z.AI model provider support to OpenClaw.
-
 ## Official external packages
 
-54 plugins
+68 plugins
 
 - **[acpx](/plugins/reference/acpx)** (`@openclaw/acpx`) - npm; ClawHub. OpenClaw ACP runtime backend with plugin-owned session and transport management.
 
@@ -217,6 +191,8 @@ Each entry lists the package, distribution route, and description.
 
 - **[chutes](/plugins/reference/chutes)** (`@openclaw/chutes-provider`) - npm; ClawHub: `clawhub:@openclaw/chutes-provider`. Adds Chutes model provider support to OpenClaw.
 
+- **[clickclack](/plugins/reference/clickclack)** (`@openclaw/clickclack`) - npm; ClawHub: `clawhub:@openclaw/clickclack`. Adds the Clickclack channel surface for sending and receiving OpenClaw messages.
+
 - **[cloudflare-ai-gateway](/plugins/reference/cloudflare-ai-gateway)** (`@openclaw/cloudflare-ai-gateway-provider`) - npm; ClawHub: `clawhub:@openclaw/cloudflare-ai-gateway-provider`. Adds Cloudflare AI Gateway model provider support to OpenClaw.
 
 - **[codex](/plugins/reference/codex)** (`@openclaw/codex`) - npm; ClawHub. OpenClaw Codex app-server harness and model provider plugin with a Codex-managed GPT catalog.
@@ -243,6 +219,8 @@ Each entry lists the package, distribution route, and description.
 
 - **[firecrawl](/plugins/reference/firecrawl)** (`@openclaw/firecrawl-plugin`) - npm; ClawHub: `clawhub:@openclaw/firecrawl-plugin`. Adds agent-callable tools. Adds web fetch provider support. Adds web search provider support.
 
+- **[fireworks](/plugins/reference/fireworks)** (`@openclaw/fireworks-provider`) - npm; ClawHub: `clawhub:@openclaw/fireworks-provider`. Adds Fireworks model provider support to OpenClaw.
+
 - **[gmi](/plugins/reference/gmi)** (`@openclaw/gmi-provider`) - npm; ClawHub: `clawhub:@openclaw/gmi-provider`. OpenClaw GMI Cloud provider plugin.
 
 - **[google-meet](/plugins/reference/google-meet)** (`@openclaw/google-meet`) - npm; ClawHub. OpenClaw Google Meet participant plugin for joining calls through Chrome or Twilio transports.
@@ -255,6 +233,8 @@ Each entry lists the package, distribution route, and description.
 
 - **[inworld](/plugins/reference/inworld)** (`@openclaw/inworld-speech`) - npm; ClawHub: `clawhub:@openclaw/inworld-speech`. Inworld streaming text-to-speech (MP3, OGG_OPUS, PCM telephony).
 
+- **[irc](/plugins/reference/irc)** (`@openclaw/irc`) - npm; ClawHub: `clawhub:@openclaw/irc`. Adds the IRC channel surface for sending and receiving OpenClaw messages.
+
 - **[kilocode](/plugins/reference/kilocode)** (`@openclaw/kilocode-provider`) - npm; ClawHub: `clawhub:@openclaw/kilocode-provider`. Adds Kilocode model provider support to OpenClaw.
 
 - **[kimi](/plugins/reference/kimi)** (`@openclaw/kimi-provider`) - npm; ClawHub: `clawhub:@openclaw/kimi-provider`. Adds Kimi, Kimi Coding model provider support to OpenClaw.
@@ -267,8 +247,12 @@ Each entry lists the package, distribution route, and description.
 
 - **[matrix](/plugins/reference/matrix)** (`@openclaw/matrix`) - ClawHub: `clawhub:@openclaw/matrix`; npm. OpenClaw Matrix channel plugin for rooms and direct messages.
 
+- **[mattermost](/plugins/reference/mattermost)** (`@openclaw/mattermost`) - npm; ClawHub: `clawhub:@openclaw/mattermost`. Adds the Mattermost channel surface for sending and receiving OpenClaw messages.
+
 - **[memory-lancedb](/plugins/reference/memory-lancedb)** (`@openclaw/memory-lancedb`) - npm; ClawHub. OpenClaw LanceDB-backed long-term memory plugin with auto-recall, auto-capture, and vector search.
 
+- **[moonshot](/plugins/reference/moonshot)** (`@openclaw/moonshot-provider`) - npm; ClawHub: `clawhub:@openclaw/moonshot-provider`. Adds Moonshot model provider support to OpenClaw.
+
 - **[msteams](/plugins/reference/msteams)** (`@openclaw/msteams`) - npm; ClawHub. OpenClaw Microsoft Teams channel plugin for bot conversations.
 
 - **[nextcloud-talk](/plugins/reference/nextcloud-talk)** (`@openclaw/nextcloud-talk`) - npm; ClawHub. OpenClaw Nextcloud Talk channel plugin for conversations.
@@ -289,22 +273,40 @@ Each entry lists the package, distribution route, and description.
 
 - **[qwen](/plugins/reference/qwen)** (`@openclaw/qwen-provider`) - npm; ClawHub: `clawhub:@openclaw/qwen-provider`. Adds Qwen, Qwen Cloud, Model Studio, DashScope, Qwen Oauth, Qwen Portal, Qwen CLI model provider support to OpenClaw.
 
+- **[raft](/plugins/reference/raft)** (`@openclaw/raft`) - npm; ClawHub. OpenClaw Raft channel plugin for secure CLI wake bridges.
+
+- **[searxng](/plugins/reference/searxng)** (`@openclaw/searxng-plugin`) - npm; ClawHub: `clawhub:@openclaw/searxng-plugin`. Adds web search provider support.
+
+- **[signal](/plugins/reference/signal)** (`@openclaw/signal`) - npm; ClawHub: `clawhub:@openclaw/signal`. Adds the Signal channel surface for sending and receiving OpenClaw messages.
+
 - **[slack](/plugins/reference/slack)** (`@openclaw/slack`) - npm; ClawHub. OpenClaw Slack channel plugin for channels, DMs, commands, and app events.
 
+- **[sms](/plugins/reference/sms)** (`@openclaw/sms`) - npm; ClawHub: `clawhub:@openclaw/sms`. Twilio SMS channel plugin for OpenClaw text messages.
+
 - **[stepfun](/plugins/reference/stepfun)** (`@openclaw/stepfun-provider`) - npm; ClawHub: `clawhub:@openclaw/stepfun-provider`. Adds StepFun, StepFun Plan model provider support to OpenClaw.
 
 - **[synology-chat](/plugins/reference/synology-chat)** (`@openclaw/synology-chat`) - npm; ClawHub. Synology Chat channel plugin for OpenClaw channels and direct messages.
 
+- **[tavily](/plugins/reference/tavily)** (`@openclaw/tavily-plugin`) - npm; ClawHub: `clawhub:@openclaw/tavily-plugin`. Adds agent-callable tools. Adds web search provider support.
+
+- **[tencent](/plugins/reference/tencent)** (`@openclaw/tencent-provider`) - npm; ClawHub: `clawhub:@openclaw/tencent-provider`. Adds Tencent TokenHub model provider support to OpenClaw.
+
 - **[tlon](/plugins/reference/tlon)** (`@openclaw/tlon`) - npm; ClawHub. OpenClaw Tlon/Urbit channel plugin for chat workflows.
 
 - **[tokenjuice](/plugins/reference/tokenjuice)** (`@openclaw/tokenjuice`) - npm; ClawHub: `clawhub:@openclaw/tokenjuice`. Compacts exec and bash tool results with tokenjuice reducers.
 
 - **[twitch](/plugins/reference/twitch)** (`@openclaw/twitch`) - npm; ClawHub. OpenClaw Twitch channel plugin for chat and moderation workflows.
 
+- **[venice](/plugins/reference/venice)** (`@openclaw/venice-provider`) - npm; ClawHub: `clawhub:@openclaw/venice-provider`. Adds Venice model provider support to OpenClaw.
+
+- **[vercel-ai-gateway](/plugins/reference/vercel-ai-gateway)** (`@openclaw/vercel-ai-gateway-provider`) - npm; ClawHub: `clawhub:@openclaw/vercel-ai-gateway-provider`. Adds Vercel AI Gateway model provider support to OpenClaw.
+
 - **[voice-call](/plugins/reference/voice-call)** (`@openclaw/voice-call`) - npm; ClawHub. OpenClaw voice-call plugin for Twilio, Telnyx, and Plivo phone calls.
 
 - **[whatsapp](/plugins/reference/whatsapp)** (`@openclaw/whatsapp`) - ClawHub: `clawhub:@openclaw/whatsapp`; npm. OpenClaw WhatsApp channel plugin for WhatsApp Web chats.
 
+- **[zai](/plugins/reference/zai)** (`@openclaw/zai-provider`) - npm; ClawHub: `clawhub:@openclaw/zai-provider`. Adds Z.AI model provider support to OpenClaw.
+
 - **[zalo](/plugins/reference/zalo)** (`@openclaw/zalo`) - npm; ClawHub. OpenClaw Zalo channel plugin for bot and webhook chats.
 
 - **[zalouser](/plugins/reference/zalouser)** (`@openclaw/zalouser`) - npm; ClawHub. OpenClaw Zalo Personal Account plugin via native zca-js integration.

docs/plugins/reference.md

@@ -15,5 +15,5 @@ This page is generated from `extensions/*/package.json` and
 pnpm plugins:inventory:gen
 ```
 
-Use [Plugin inventory](/plugins/plugin-inventory) to browse all 128
+Use [Plugin inventory](/plugins/plugin-inventory) to browse all 129
 generated plugin reference pages by distribution, package, and description.

docs/plugins/reference/canvas.md

@@ -16,4 +16,4 @@ Experimental Canvas control and A2UI rendering surfaces for paired nodes.
 
 ## Surface
 
-contracts: tools
+contracts: tools; skills

docs/plugins/reference/clickclack.md

@@ -12,7 +12,7 @@ Adds the Clickclack channel surface for sending and receiving OpenClaw messages.
 ## Distribution
 
 - Package: `@openclaw/clickclack`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/clickclack`
 
 ## Surface
 

docs/plugins/reference/discord.md

@@ -16,7 +16,7 @@ OpenClaw Discord channel plugin for channels, DMs, commands, and app events.
 
 ## Surface
 
-channels: discord; contracts: transcriptSourceProviders
+channels: discord; contracts: transcriptSourceProviders; skills
 
 ## Related docs
 

docs/plugins/reference/fireworks.md

@@ -12,7 +12,7 @@ Adds Fireworks model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/fireworks-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/fireworks-provider`
 
 ## Surface
 

docs/plugins/reference/irc.md

@@ -12,7 +12,7 @@ Adds the IRC channel surface for sending and receiving OpenClaw messages.
 ## Distribution
 
 - Package: `@openclaw/irc`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/irc`
 
 ## Surface
 

docs/plugins/reference/mattermost.md

@@ -12,7 +12,7 @@ Adds the Mattermost channel surface for sending and receiving OpenClaw messages.
 ## Distribution
 
 - Package: `@openclaw/mattermost`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/mattermost`
 
 ## Surface
 

docs/plugins/reference/moonshot.md

@@ -12,7 +12,7 @@ Adds Moonshot model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/moonshot-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/moonshot-provider`
 
 ## Surface
 

docs/plugins/reference/raft.md

@@ -0,0 +1,23 @@
+---
+summary: "OpenClaw Raft channel plugin for secure CLI wake bridges."
+read_when:
+  - You are installing, configuring, or auditing the raft plugin
+title: "Raft plugin"
+---
+
+# Raft plugin
+
+OpenClaw Raft channel plugin for secure CLI wake bridges.
+
+## Distribution
+
+- Package: `@openclaw/raft`
+- Install route: npm; ClawHub
+
+## Surface
+
+channels: raft
+
+## Related docs
+
+- [raft](/channels/raft)

docs/plugins/reference/searxng.md

@@ -12,7 +12,7 @@ Adds web search provider support.
 ## Distribution
 
 - Package: `@openclaw/searxng-plugin`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/searxng-plugin`
 
 ## Surface
 

docs/plugins/reference/signal.md

@@ -12,7 +12,7 @@ Adds the Signal channel surface for sending and receiving OpenClaw messages.
 ## Distribution
 
 - Package: `@openclaw/signal`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/signal`
 
 ## Surface
 

docs/plugins/reference/slack.md

@@ -16,7 +16,7 @@ OpenClaw Slack channel plugin for channels, DMs, commands, and app events.
 
 ## Surface
 
-channels: slack
+channels: slack; skills
 
 ## Related docs
 

docs/plugins/reference/sms.md

@@ -12,7 +12,7 @@ Twilio SMS channel plugin for OpenClaw text messages.
 ## Distribution
 
 - Package: `@openclaw/sms`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/sms`
 
 ## Surface
 

docs/plugins/reference/tavily.md

@@ -12,7 +12,7 @@ Adds agent-callable tools. Adds web search provider support.
 ## Distribution
 
 - Package: `@openclaw/tavily-plugin`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/tavily-plugin`
 
 ## Surface
 

docs/plugins/reference/tencent.md

@@ -12,7 +12,7 @@ Adds Tencent TokenHub model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/tencent-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/tencent-provider`
 
 ## Surface
 

docs/plugins/reference/venice.md

@@ -12,7 +12,7 @@ Adds Venice model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/venice-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/venice-provider`
 
 ## Surface
 

docs/plugins/reference/vercel-ai-gateway.md

@@ -12,7 +12,7 @@ Adds Vercel AI Gateway model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/vercel-ai-gateway-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/vercel-ai-gateway-provider`
 
 ## Surface
 

docs/plugins/reference/voice-call.md

@@ -16,7 +16,7 @@ OpenClaw voice-call plugin for Twilio, Telnyx, and Plivo phone calls.
 
 ## Surface
 
-contracts: tools
+contracts: tools; skills
 
 ## Related docs
 

docs/plugins/reference/whatsapp.md

@@ -16,7 +16,7 @@ OpenClaw WhatsApp channel plugin for WhatsApp Web chats.
 
 ## Surface
 
-channels: whatsapp
+channels: whatsapp; skills
 
 ## Related docs
 

docs/plugins/reference/zai.md

@@ -12,7 +12,7 @@ Adds Z.AI model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/zai-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/zai-provider`
 
 ## Surface
 

docs/plugins/sdk-migration.md

@@ -238,11 +238,9 @@ releases.
     `api.runtime.config.writeConfigFile(...)` directly. Prefer config that was
     already passed into the active call path. Long-lived handlers that need the
     current process snapshot can use `api.runtime.config.current()`. Long-lived
-    factory-created agent tools should use the tool factory context's
-    `ctx.getRuntimeConfig()` inside `execute` so a tool created before a config
-    write still sees the refreshed runtime config. For per-call run, session, or
-    delivery facts, use the tool execution context rather than closing over the
-    factory context.
+    agent tools should use the tool context's `ctx.getRuntimeConfig()` inside
+    `execute` so a tool created before a config write still sees the refreshed
+    runtime config.
 
     Config writes must go through the transactional helpers and choose an
     after-write policy:

docs/plugins/sdk-provider-plugins.md

@@ -515,7 +515,7 @@ API key auth, and dynamic model resolution.
 
       - `openclaw/plugin-sdk/provider-model-shared` - `ProviderReplayFamily`, `buildProviderReplayFamilyHooks(...)`, and the raw replay builders (`buildOpenAICompatibleReplayPolicy`, `buildAnthropicReplayPolicyForModel`, `buildGoogleGeminiReplayPolicy`, `buildHybridAnthropicOrOpenAIReplayPolicy`). Also exports Gemini replay helpers (`sanitizeGoogleGeminiReplayHistory`, `resolveTaggedReasoningOutputMode`) and endpoint/model helpers (`resolveProviderEndpoint`, `normalizeProviderId`, `normalizeGooglePreviewModelId`).
       - `openclaw/plugin-sdk/provider-stream` - `ProviderStreamFamily`, `buildProviderStreamFamilyHooks(...)`, `composeProviderStreamWrappers(...)`, plus the shared OpenAI/Codex wrappers (`createOpenAIAttributionHeadersWrapper`, `createOpenAIFastModeWrapper`, `createOpenAIServiceTierWrapper`, `createOpenAIResponsesContextManagementWrapper`, `createCodexNativeWebSearchWrapper`), DeepSeek V4 OpenAI-compatible wrapper (`createDeepSeekV4OpenAICompatibleThinkingWrapper`), Anthropic Messages thinking prefill cleanup (`createAnthropicThinkingPrefillPayloadWrapper`), plain-text tool-call compat (`createPlainTextToolCallCompatWrapper`), and shared proxy/provider wrappers (`createOpenRouterWrapper`, `createToolStreamWrapper`, `createMinimaxFastModeWrapper`).
-      - `openclaw/plugin-sdk/provider-stream-shared` - lightweight payload and event wrappers for hot provider paths, including `createOpenAICompatibleCompletionsThinkingOffWrapper`, `createPayloadPatchStreamWrapper`, and `createPlainTextToolCallCompatWrapper`.
+      - `openclaw/plugin-sdk/provider-stream-shared` - lightweight payload and event wrappers for hot provider paths, including `createOpenAICompatibleCompletionsThinkingOffWrapper`, `createPayloadPatchStreamWrapper`, `createPlainTextToolCallCompatWrapper`, and `setQwenChatTemplateThinking(...)`.
       - `openclaw/plugin-sdk/provider-tools` - `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks("deepseek" | "gemini" | "openai")`, and underlying provider schema helpers.
 
       For Gemini-family providers, keep the reasoning-output mode aligned with

docs/plugins/sdk-subpaths.md

@@ -164,7 +164,7 @@ and pairing-path families.
     | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, and DeepSeek/Gemini/OpenAI schema cleanup + diagnostics |
     | `plugin-sdk/provider-usage` | Provider usage snapshot types, shared usage fetch helpers, and provider fetchers such as `fetchClaudeUsage` |
     | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, stream wrapper types, plain-text tool-call compat, and shared Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot wrapper helpers |
-    | `plugin-sdk/provider-stream-shared` | Public shared provider stream wrapper helpers including `composeProviderStreamWrappers`, `createOpenAICompatibleCompletionsThinkingOffWrapper`, `createPlainTextToolCallCompatWrapper`, `createPayloadPatchStreamWrapper`, `createToolStreamWrapper`, and Anthropic/DeepSeek/OpenAI-compatible stream utilities |
+    | `plugin-sdk/provider-stream-shared` | Public shared provider stream wrapper helpers including `composeProviderStreamWrappers`, `createOpenAICompatibleCompletionsThinkingOffWrapper`, `createPlainTextToolCallCompatWrapper`, `createPayloadPatchStreamWrapper`, `createToolStreamWrapper`, `setQwenChatTemplateThinking`, and Anthropic/DeepSeek/OpenAI-compatible stream utilities |
     | `plugin-sdk/provider-transport-runtime` | Native provider transport helpers such as guarded fetch, transport message transforms, and writable transport event streams |
     | `plugin-sdk/provider-onboard` | Onboarding config patch helpers |
     | `plugin-sdk/global-singleton` | Process-local singleton/map/cache helpers |

docs/plugins/tool-plugins.md

@@ -151,14 +151,6 @@ Factories are still for fixed tool names. Use `definePluginEntry` directly when
 the plugin computes tool names dynamically or combines tools with hooks,
 services, providers, commands, or other runtime surfaces.
 
-Factory context is construction-time state. Use it to decide whether the tool
-exists for the run or to bind stable helpers. Per-call state belongs in the
-execution context: static tool-plugin `execute` handlers receive it as fields on
-their third `context` argument, and factory-created `AgentTool.execute`
-handlers receive it as the optional fifth argument. The execution context
-includes `runId`, effective `sessionKey`, `sessionId`, `agentId`, and
-`deliveryContext` when OpenClaw knows those values.
-
 ## Return values
 
 `defineToolPlugin` wraps plain return values into the OpenClaw tool-result

docs/plugins/voice-call.md

@@ -759,7 +759,7 @@ Tool name: `voice_call`.
 | `end_call`      | `callId`                                   |
 | `get_status`    | `callId`                                   |
 
-This repo ships a matching skill doc at `skills/voice-call/SKILL.md`.
+The voice-call plugin ships a matching agent skill.
 
 ## Gateway RPC
 

docs/providers/fireworks.md

@@ -7,12 +7,12 @@ read_when:
   - You are debugging Kimi thinking-off behavior on Fireworks
 ---
 
-[Fireworks](https://fireworks.ai) exposes open-weight and routed models through an OpenAI-compatible API. OpenClaw includes a bundled Fireworks provider plugin that ships with two pre-cataloged Kimi models and accepts any Fireworks model or router id at runtime.
+[Fireworks](https://fireworks.ai) exposes open-weight and routed models through an OpenAI-compatible API. Install the official Fireworks provider plugin to use two pre-cataloged Kimi models and any Fireworks model or router id at runtime.
 
 | Property        | Value                                                  |
 | --------------- | ------------------------------------------------------ |
 | Provider id     | `fireworks` (alias: `fireworks-ai`)                    |
-| Plugin          | bundled, `enabledByDefault: true`                      |
+| Package         | `@openclaw/fireworks-provider`                         |
 | Auth env var    | `FIREWORKS_API_KEY`                                    |
 | Onboarding flag | `--auth-choice fireworks-api-key`                      |
 | Direct CLI flag | `--fireworks-api-key <key>`                            |
@@ -24,6 +24,11 @@ read_when:
 ## Getting started
 
 <Steps>
+  <Step title="Install the plugin">
+    ```bash
+    openclaw plugins install @openclaw/fireworks-provider
+    ```
+  </Step>
   <Step title="Set the Fireworks API key">
     <CodeGroup>
 
@@ -108,7 +113,7 @@ OpenClaw accepts any Fireworks model or router id at runtime. Use the exact id s
   </Accordion>
 
   <Accordion title="Why thinking is forced off for Kimi">
-    Fireworks K2.6 returns a 400 if the request carries `reasoning_*` parameters even though Kimi supports thinking through Moonshot's own API. The bundled policy (`extensions/fireworks/thinking-policy.ts`) advertises only the `off` thinking level for Kimi model ids, so manual `/think` switches and provider-policy surfaces stay aligned with the runtime contract.
+    Fireworks K2.6 returns a 400 if the request carries `reasoning_*` parameters even though Kimi supports thinking through Moonshot's own API. The provider policy (`extensions/fireworks/thinking-policy.ts`) advertises only the `off` thinking level for Kimi model ids, so manual `/think` switches and provider-policy surfaces stay aligned with the runtime contract.
 
     To use Kimi reasoning end-to-end, configure the [Moonshot provider](/providers/moonshot) and route the same model through it.
 

docs/providers/moonshot.md

@@ -30,7 +30,7 @@ Moonshot and Kimi Coding are **separate providers**. Keys are not interchangeabl
 
 [//]: # "moonshot-kimi-k2-ids:end"
 
-Bundled cost estimates for current Moonshot-hosted K2 models use Moonshot's
+Catalog cost estimates for current Moonshot-hosted K2 models use Moonshot's
 published pay-as-you-go rates: Kimi K2.7 Code is $0.19/MTok cache hit,
 $0.95/MTok input, and $4.00/MTok output; Kimi K2.6 is $0.16/MTok cache hit,
 $0.95/MTok input, and $4.00/MTok output; Kimi K2.5 is $0.10/MTok cache hit,
@@ -213,6 +213,11 @@ Choose your provider and follow the setup steps.
     </Note>
 
     <Steps>
+      <Step title="Install the plugin">
+        ```bash
+        openclaw plugins install @openclaw/kimi-provider
+        ```
+      </Step>
       <Step title="Run onboarding">
         ```bash
         openclaw onboard --auth-choice kimi-code-api-key
@@ -257,8 +262,7 @@ Choose your provider and follow the setup steps.
 
 ## Kimi web search
 
-OpenClaw also ships **Kimi** as a `web_search` provider, backed by Moonshot web
-search.
+The Moonshot plugin also registers **Kimi** as a `web_search` provider, backed by Moonshot web search.
 
 <Steps>
   <Step title="Run interactive web search setup">
@@ -405,7 +409,7 @@ Config lives under `plugins.entries.moonshot.config.webSearch`:
     capabilities, so compatible custom provider ids targeting the same native
     Moonshot hosts inherit the same streaming-usage behavior.
 
-    With the bundled K2.6 pricing, streamed usage that includes input, output,
+    With the catalog K2.6 pricing, streamed usage that includes input, output,
     and cache-read tokens is also converted into local estimated USD cost for
     `/status`, `/usage full`, `/usage cost`, and transcript-backed session
     accounting.

docs/providers/openai.md

@@ -915,17 +915,17 @@ the Server-side compaction accordion below.
   <Accordion title="Fast mode">
     OpenClaw exposes a shared fast-mode toggle for `openai/*`:
 
-    - **Chat/UI:** `/fast status|on|off`
+    - **Chat/UI:** `/fast status|auto|on|off`
     - **Config:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
 
-    When enabled, OpenClaw maps fast mode to OpenAI priority processing (`service_tier = "priority"`). Existing `service_tier` values are preserved, and fast mode does not rewrite `reasoning` or `text.verbosity`.
+    When enabled, OpenClaw maps fast mode to OpenAI priority processing (`service_tier = "priority"`). Existing `service_tier` values are preserved, and fast mode does not rewrite `reasoning` or `text.verbosity`. `fastMode: "auto"` starts new model calls fast until the auto cutoff, then starts later retry, fallback, tool-result, or continuation calls without fast mode. The cutoff defaults to 60 seconds; set `params.fastAutoOnSeconds` on the active model to change it.
 
     ```json5
     {
       agents: {
         defaults: {
           models: {
-            "openai/gpt-5.5": { params: { fastMode: true } },
+            "openai/gpt-5.5": { params: { fastMode: "auto", fastAutoOnSeconds: 30 } },
           },
         },
       },

docs/providers/tencent.md

@@ -6,12 +6,12 @@ read_when:
   - You need the TokenHub API key setup
 ---
 
-Tencent Cloud ships as a bundled provider plugin in OpenClaw. It gives access to Tencent Hy3 preview through the TokenHub endpoint (`tencent-tokenhub`) using an OpenAI-compatible API.
+Install the official Tencent Cloud provider plugin to access Tencent Hy3 preview through the TokenHub endpoint (`tencent-tokenhub`) using an OpenAI-compatible API.
 
 | Property         | Value                                                 |
 | ---------------- | ----------------------------------------------------- |
 | Provider id      | `tencent-tokenhub`                                    |
-| Plugin           | bundled, `enabledByDefault: true`                     |
+| Package          | `@openclaw/tencent-provider`                          |
 | Auth env var     | `TOKENHUB_API_KEY`                                    |
 | Onboarding flag  | `--auth-choice tokenhub-api-key`                      |
 | Direct CLI flag  | `--tokenhub-api-key <key>`                            |
@@ -23,6 +23,11 @@ Tencent Cloud ships as a bundled provider plugin in OpenClaw. It gives access to
 ## Quick start
 
 <Steps>
+  <Step title="Install the plugin">
+    ```bash
+    openclaw plugins install @openclaw/tencent-provider
+    ```
+  </Step>
   <Step title="Create a TokenHub API key">
     Create an API key in Tencent Cloud TokenHub. If you choose a limited access scope for the key, include **Hy3 preview** in the allowed models.
   </Step>
@@ -78,7 +83,7 @@ Hy3 preview is Tencent Hunyuan's large MoE language model for reasoning, long-co
 
 ## Tiered pricing
 
-The bundled catalog ships tiered cost metadata that scales with input window length, so cost estimates are populated without manual overrides.
+The provider catalog ships tiered cost metadata that scales with input window length, so cost estimates are populated without manual overrides.
 
 | Input tokens range | Input rate | Output rate | Cache read |
 | ------------------ | ---------- | ----------- | ---------- |

docs/providers/venice.md

@@ -42,6 +42,11 @@ Anonymized models are **not** fully private. Venice strips metadata before forwa
 ## Getting started
 
 <Steps>
+  <Step title="Install the plugin">
+    ```bash
+    openclaw plugins install @openclaw/venice-provider
+    ```
+  </Step>
   <Step title="Get your API key">
     1. Sign up at [venice.ai](https://venice.ai)
     2. Go to **Settings > API Keys > Create new key**

docs/providers/vercel-ai-gateway.md

@@ -9,12 +9,13 @@ read_when:
 The [Vercel AI Gateway](https://vercel.com/ai-gateway) provides a unified API to
 access hundreds of models through a single endpoint.
 
-| Property      | Value                            |
-| ------------- | -------------------------------- |
-| Provider      | `vercel-ai-gateway`              |
-| Auth          | `AI_GATEWAY_API_KEY`             |
-| API           | Anthropic Messages compatible    |
-| Model catalog | Auto-discovered via `/v1/models` |
+| Property      | Value                                  |
+| ------------- | -------------------------------------- |
+| Provider      | `vercel-ai-gateway`                    |
+| Package       | `@openclaw/vercel-ai-gateway-provider` |
+| Auth          | `AI_GATEWAY_API_KEY`                   |
+| API           | Anthropic Messages compatible          |
+| Model catalog | Auto-discovered via `/v1/models`       |
 
 <Tip>
 OpenClaw auto-discovers the Gateway `/v1/models` catalog, so
@@ -26,6 +27,11 @@ OpenClaw auto-discovers the Gateway `/v1/models` catalog, so
 ## Getting started
 
 <Steps>
+  <Step title="Install the plugin">
+    ```bash
+    openclaw plugins install @openclaw/vercel-ai-gateway-provider
+    ```
+  </Step>
   <Step title="Set the API key">
     Run onboarding and choose the AI Gateway auth option:
 

docs/providers/zai.md

@@ -13,6 +13,7 @@ OpenClaw uses the `zai` provider with a Z.AI API key.
 | Property | Value                                        |
 | -------- | -------------------------------------------- |
 | Provider | `zai`                                        |
+| Package  | `@openclaw/zai-provider`                     |
 | Auth     | `ZAI_API_KEY` (legacy alias: `Z_AI_API_KEY`) |
 | API      | Z.AI Chat Completions (Bearer auth)          |
 
@@ -23,6 +24,12 @@ refs such as `zai/glm-5.2`: provider `zai`, model id `glm-5.2`.
 
 ## Getting started
 
+Install the provider plugin first:
+
+```bash
+openclaw plugins install @openclaw/zai-provider
+```
+
 <Tabs>
   <Tab title="Auto-detect endpoint">
     **Best for:** most users. OpenClaw probes supported Z.AI endpoints with your API key and applies the correct base URL automatically.
@@ -96,7 +103,7 @@ you want to force a specific Coding Plan or general API surface.
 
 ## Built-in catalog
 
-OpenClaw ships the bundled `zai` provider catalog in the plugin manifest, so read-only
+The `zai` provider plugin ships its catalog in the plugin manifest, so read-only
 listing can show known GLM rows without loading provider runtime:
 
 ```bash
@@ -143,7 +150,7 @@ known to your installed version.
 
 <AccordionGroup>
   <Accordion title="Forward-resolving unknown GLM-5 models">
-    Unknown `glm-5*` ids still forward-resolve on the bundled provider path by
+    Unknown `glm-5*` ids still forward-resolve on the provider path by
     synthesizing provider-owned metadata from the `glm-4.7` template when the id
     matches the current GLM-5 family shape.
   </Accordion>
@@ -200,7 +207,7 @@ known to your installed version.
   </Accordion>
 
   <Accordion title="Image understanding">
-    The bundled Z.AI plugin registers image understanding.
+    The Z.AI plugin registers image understanding.
 
     | Property      | Value       |
     | ------------- | ----------- |

docs/reference/RELEASING.md

@@ -191,10 +191,11 @@ release state.
    closeout requires both assets and a matching checksum. A partial manifest
    replays its recorded `main` SHA and rollback drill to regenerate identical
    bytes, then attaches the missing checksum; an invalid pair, or a checksum
-   without a manifest, stays blocking. A missing or more-than-90-day-old drill
-   record blocks a new evidence-backed closeout; private recovery commands
-   remain in the maintainer-only runbook. Use manual dispatch only to repair or
-   replay an evidence-backed stable closeout.
+   without a manifest, stays blocking. A push-triggered run without rollback
+   drill repository variables skips without completing closeout; a missing or
+   more-than-90-day-old drill record still blocks manual evidence-backed
+   closeout. Private recovery commands remain in the maintainer-only runbook.
+   Use manual dispatch only to repair or replay an evidence-backed stable closeout.
    A legacy fallback correction tag may reuse base-package evidence only when
    the correction tag resolves to the same source commit as the base stable tag.
    A correction with different source must publish and verify its own package

docs/tools/searxng-search.md

@@ -20,6 +20,11 @@ Advantages:
 ## Setup
 
 <Steps>
+  <Step title="Install the plugin">
+    ```bash
+    openclaw plugins install @openclaw/searxng-plugin
+    ```
+  </Step>
   <Step title="Run a SearXNG instance">
     ```bash
     docker run -d -p 8888:8080 searxng/searxng

docs/tools/slash-commands.md

@@ -198,7 +198,7 @@ plugins.
     | `/think <level\|default>` | Set the thinking level or clear the session override. Aliases: `/thinking`, `/t` |
     | `/verbose on\|off\|full` | Toggle verbose output. Alias: `/v` |
     | `/trace on\|off` | Toggle plugin trace output for the current session |
-    | `/fast [status\|on\|off\|default]` | Show, set, or clear fast mode |
+    | `/fast [status\|auto\|on\|off\|default]` | Show, set, or clear fast mode |
     | `/reasoning [on\|off\|stream]` | Toggle reasoning visibility. Alias: `/reason` |
     | `/elevated [on\|off\|ask\|full]` | Toggle elevated mode. Alias: `/elev` |
     | `/exec host=<auto\|sandbox\|gateway\|node> security=<deny\|allowlist\|full> ask=<off\|on-miss\|always> node=<id>` | Show or set exec defaults |
@@ -211,7 +211,7 @@ plugins.
       <Accordion title="verbose / trace / fast / reasoning safety">
         - `/verbose` is for debugging — keep it **off** in normal use.
         - `/trace` reveals only plugin-owned trace/debug lines; normal verbose chatter stays off.
-        - `/fast on|off` persists a session override; use the Sessions UI `inherit` option to clear it.
+        - `/fast auto|on|off` persists a session override; use the Sessions UI `inherit` option to clear it.
         - `/fast` is provider-specific: OpenAI/Codex map it to `service_tier=priority`; direct Anthropic requests map it to `service_tier=auto` or `standard_only`.
         - `/reasoning`, `/verbose`, and `/trace` are risky in group settings — they may reveal internal reasoning or plugin diagnostics. Keep them off in group chats.
 

docs/tools/tavily.md

@@ -15,16 +15,22 @@ title: "Tavily"
 
 Tavily returns structured results optimized for LLM consumption with configurable search depth, topic filtering, domain filters, AI-generated answer summaries, and content extraction from URLs (including JavaScript-rendered pages).
 
-| Property      | Value                               |
-| ------------- | ----------------------------------- |
-| Plugin id     | `tavily`                            |
-| Auth          | `TAVILY_API_KEY` or config `apiKey` |
-| Base URL      | `https://api.tavily.com` (default)  |
-| Bundled tools | `tavily_search`, `tavily_extract`   |
+| Property  | Value                               |
+| --------- | ----------------------------------- |
+| Plugin id | `tavily`                            |
+| Package   | `@openclaw/tavily-plugin`           |
+| Auth      | `TAVILY_API_KEY` or config `apiKey` |
+| Base URL  | `https://api.tavily.com` (default)  |
+| Tools     | `tavily_search`, `tavily_extract`   |
 
 ## Getting started
 
 <Steps>
+  <Step title="Install the plugin">
+    ```bash
+    openclaw plugins install @openclaw/tavily-plugin
+    ```
+  </Step>
   <Step title="Get an API key">
     Create a Tavily account at [tavily.com](https://tavily.com), then generate an API key in the dashboard.
   </Step>
@@ -60,7 +66,7 @@ Tavily returns structured results optimized for LLM consumption with configurabl
 </Steps>
 
 <Tip>
-Choosing Tavily in onboarding or `openclaw configure --section web` enables the bundled Tavily plugin automatically.
+Choosing Tavily in onboarding or `openclaw configure --section web` installs and enables the official Tavily plugin when needed.
 </Tip>
 
 ## Tool reference

docs/tools/thinking.md

@@ -60,21 +60,22 @@ title: "Thinking levels"
 
 ## Fast mode (/fast)
 
-- Levels: `on|off|default`.
-- Directive-only message toggles a session fast-mode override and replies `Fast mode enabled.` / `Fast mode disabled.`. Use `/fast default` to clear the session override and inherit the configured default; aliases include `inherit`, `clear`, `reset`, and `unpin`.
+- Levels: `auto|on|off|default`.
+- Directive-only message toggles a session fast-mode override and replies `Fast mode set to auto.`, `Fast mode enabled.`, or `Fast mode disabled.`. Use `/fast default` to clear the session override and inherit the configured default; aliases include `inherit`, `clear`, `reset`, and `unpin`.
 - Send `/fast` (or `/fast status`) with no mode to see the current effective fast-mode state.
 - OpenClaw resolves fast mode in this order:
-  1. Inline/directive-only `/fast on|off` override (`/fast default` clears this layer)
+  1. Inline/directive-only `/fast auto|on|off` override (`/fast default` clears this layer)
   2. Session override
   3. Per-agent default (`agents.list[].fastModeDefault`)
   4. Per-model config: `agents.defaults.models["<provider>/<model>"].params.fastMode`
   5. Fallback: `off`
+- `auto` keeps the session/config mode as auto but resolves each new model call independently. Calls that start before the auto cutoff have fast mode enabled; later retry, fallback, tool-result, or continuation calls start with fast mode disabled. The cutoff defaults to 60 seconds; set `agents.defaults.models["<provider>/<model>"].params.fastAutoOnSeconds` on the active model to change it.
 - For `openai/*`, fast mode maps to OpenAI priority processing by sending `service_tier=priority` on supported Responses requests.
-- For Codex-backed `openai/*` models, fast mode sends the same `service_tier=priority` flag on Codex Responses. OpenClaw keeps one shared `/fast` toggle across both auth paths.
+- For Codex-backed `openai/*` / `openai-codex/*` models, fast mode sends the same `service_tier=priority` flag on Codex Responses. Native Codex app-server turns receive the tier only on `turn/start` or thread start/resume, so `auto` cannot retier one already-running app-server turn; it applies to the next model turn OpenClaw starts.
 - For direct public `anthropic/*` requests, including OAuth-authenticated traffic sent to `api.anthropic.com`, fast mode maps to Anthropic service tiers: `/fast on` sets `service_tier=auto`, `/fast off` sets `service_tier=standard_only`.
 - For `minimax/*` on the Anthropic-compatible path, `/fast on` (or `params.fastMode: true`) rewrites `MiniMax-M2.7` to `MiniMax-M2.7-highspeed`.
 - Explicit Anthropic `serviceTier` / `service_tier` model params override the fast-mode default when both are set. OpenClaw still skips Anthropic service-tier injection for non-Anthropic proxy base URLs.
-- `/status` shows `Fast` only when fast mode is enabled.
+- `/status` shows `Fast` when fast mode is enabled and `Fast:auto` when the configured mode is auto.
 
 ## Verbose directives (/verbose or /v)
 

extensions/active-memory/index.test.ts

@@ -844,6 +844,79 @@ describe("active-memory plugin", () => {
     expect(runEmbeddedAgent).not.toHaveBeenCalled();
   });
 
+  it("does not run for dreaming-narrative cron session keys", async () => {
+    const result = await hooks.before_prompt_build(
+      { prompt: "what wings should i order?", messages: [] },
+      {
+        agentId: "main",
+        trigger: "user",
+        sessionKey: "agent:main:dreaming-narrative-light-abc123",
+        messageProvider: "webchat",
+      },
+    );
+
+    expect(result).toBeUndefined();
+    expect(runEmbeddedAgent).not.toHaveBeenCalled();
+  });
+
+  it("does not run when a session id resolves to a dreaming-narrative cron session key", async () => {
+    hoisted.sessionStore["agent:main:dreaming-narrative-light-abc123"] = {
+      sessionId: "dreaming-session",
+      updatedAt: 1,
+    };
+
+    const result = await hooks.before_prompt_build(
+      { prompt: "what wings should i order?", messages: [] },
+      {
+        agentId: "main",
+        trigger: "user",
+        sessionId: "dreaming-session",
+        messageProvider: "webchat",
+      },
+    );
+
+    expect(result).toBeUndefined();
+    expect(runEmbeddedAgent).not.toHaveBeenCalled();
+  });
+
+  it("allows non-canonical session keys that merely contain the dreaming-narrative substring", async () => {
+    const result = await hooks.before_prompt_build(
+      { prompt: "what wings should i order?", messages: [] },
+      {
+        agentId: "main",
+        trigger: "user",
+        sessionKey: "agent:main:webchat:dreaming-narrative-room",
+        messageProvider: "webchat",
+      },
+    );
+
+    // Real session keys that happen to contain "dreaming-narrative" in a
+    // non-canonical way (not {light|rem|deep} phase suffix) must remain eligible.
+    // The session key "agent:main:webchat:dreaming-narrative-room" is a real chat
+    // whose topic happens to contain the string — not a dreaming cron key.
+    expect(runEmbeddedAgent).toHaveBeenCalledTimes(1);
+    expect(result).not.toBeUndefined();
+  });
+
+  it("allows real webchat session keys whose peer id starts with a phased dreaming-narrative prefix", async () => {
+    const result = await hooks.before_prompt_build(
+      { prompt: "what wings should i order?", messages: [] },
+      {
+        agentId: "main",
+        trigger: "user",
+        sessionKey: "agent:main:webchat:dreaming-narrative-light-room",
+        messageProvider: "webchat",
+      },
+    );
+
+    // A real webchat session key whose peer id begins with a phased dreaming-narrative
+    // phrase must not be excluded. Only the canonical bare or agent-prefixed key
+    // shape (dreaming-narrative-<phase>-<hash> directly after agentId or bare) should
+    // be rejected — not the same phrase appearing deeper in the key as a peer id.
+    expect(runEmbeddedAgent).toHaveBeenCalledTimes(1);
+    expect(result).not.toBeUndefined();
+  });
+
   it("defaults to direct-style sessions only", async () => {
     const result = await hooks.before_prompt_build(
       { prompt: "what wings should we order?", messages: [] },

extensions/active-memory/index.ts

@@ -1155,6 +1155,19 @@ function isEligibleInteractiveSession(ctx: {
   if (ctx.trigger !== "user") {
     return false;
   }
+  // Exclude only canonical dreaming-narrative session keys (bare or agent-prefixed).
+  // Canonical forms: "dreaming-narrative-<phase>-<hash>" or
+  // "agent:<agentId>:dreaming-narrative-<phase>-<hash>".
+  // A colon-delimited match would also exclude real chat session ids whose peer id
+  // begins with a phased dreaming-narrative phrase (e.g.
+  // "agent:main:feishu:group:dreaming-narrative-light-room").
+  const sessionKey = ctx.sessionKey ?? "";
+  if (
+    /^dreaming-narrative-(light|rem|deep)-/i.test(sessionKey) ||
+    /^agent:[^:]+:dreaming-narrative-(light|rem|deep)-/i.test(sessionKey)
+  ) {
+    return false;
+  }
   if (!ctx.sessionKey && !ctx.sessionId) {
     return false;
   }
@@ -3617,7 +3630,12 @@ export default definePluginEntry({
               });
               return undefined;
             }
-            if (!isEligibleInteractiveSession(ctx)) {
+            if (
+              !isEligibleInteractiveSession({
+                ...ctx,
+                sessionKey: resolvedSessionKey ?? ctx.sessionKey,
+              })
+            ) {
               await persistPluginStatusLines({
                 api,
                 agentId: effectiveAgentId,

extensions/anthropic/cli-backend.ts

@@ -49,7 +49,7 @@ export function buildAnthropicCliBackend(): CliBackendPlugin {
         "--allowedTools",
         "mcp__openclaw__*",
         "--disallowedTools",
-        "ScheduleWakeup,CronCreate",
+        "ScheduleWakeup,CronCreate,Bash(run_in_background:true),Monitor",
       ],
       resumeArgs: [
         "-p",
@@ -62,7 +62,7 @@ export function buildAnthropicCliBackend(): CliBackendPlugin {
         "--allowedTools",
         "mcp__openclaw__*",
         "--disallowedTools",
-        "ScheduleWakeup,CronCreate",
+        "ScheduleWakeup,CronCreate,Bash(run_in_background:true),Monitor",
         "--resume",
         "{sessionId}",
       ],

extensions/anthropic/cli-shared.test.ts

@@ -10,10 +10,13 @@ import {
   resolveClaudeCliExecutionArgs,
 } from "./cli-shared.js";
 
+const CLAUDE_CLI_DISALLOWED_TOOLS =
+  "ScheduleWakeup,CronCreate,Bash(run_in_background:true),Monitor";
+
 function expectDefaultDisallowedTools(args: readonly string[] | undefined) {
   const disallowedIndex = args?.indexOf("--disallowedTools") ?? -1;
   expect(disallowedIndex).toBeGreaterThanOrEqual(0);
-  expect(args?.[disallowedIndex + 1]).toBe("ScheduleWakeup,CronCreate");
+  expect(args?.[disallowedIndex + 1]).toBe(CLAUDE_CLI_DISALLOWED_TOOLS);
 }
 
 describe("normalizeClaudePermissionArgs", () => {
@@ -382,4 +385,11 @@ describe("normalizeClaudeBackendConfig", () => {
     expect(backend.config.clearEnv).toContain("OTEL_EXPORTER_OTLP_PROTOCOL");
     expect(backend.config.clearEnv).toContain("OTEL_SDK_DISABLED");
   });
+
+  it("disables native background Bash and Monitor tools in args and resumeArgs", () => {
+    const backend = buildAnthropicCliBackend();
+
+    expectDefaultDisallowedTools(backend.config.args);
+    expectDefaultDisallowedTools(backend.config.resumeArgs);
+  });
 });

extensions/anthropic/stream-wrappers.test.ts

@@ -8,6 +8,7 @@ import {
   createAnthropicServiceTierWrapper,
   createAnthropicThinkingPrefillWrapper,
   resolveAnthropicBetas,
+  resolveAnthropicFastMode,
   wrapAnthropicProviderStream,
 } from "./stream-wrappers.js";
 
@@ -172,6 +173,10 @@ describe("anthropic stream wrappers", () => {
     expect(captured.headers?.["anthropic-beta"]).toContain(OAUTH_BETA);
     expect(captured.headers?.["anthropic-beta"]).not.toContain(CONTEXT_1M_BETA);
   });
+
+  it("ignores unresolved auto fast mode at the provider boundary", () => {
+    expect(resolveAnthropicFastMode({ fastMode: "auto" })).toBeUndefined();
+  });
 });
 
 describe("createAnthropicThinkingPrefillWrapper", () => {
@@ -282,6 +287,19 @@ describe("Anthropic service_tier payload wrappers", () => {
     expect(payload?.service_tier).toBe("standard_only");
   });
 
+  it("fast mode resolves dynamic service_tier for each stream call", () => {
+    let enabled = true;
+    const first = runPayloadWrapper({ apiKey: "sk-ant-api03-test-key" }, (base) =>
+      createAnthropicFastModeWrapper(base, () => enabled),
+    );
+    enabled = false;
+    const second = runPayloadWrapper({ apiKey: "sk-ant-api03-test-key" }, (base) =>
+      createAnthropicFastModeWrapper(base, () => enabled),
+    );
+    expect(first?.service_tier).toBe("auto");
+    expect(second?.service_tier).toBe("standard_only");
+  });
+
   it("explicit service tier injects service_tier=standard_only for regular API keys", () => {
     const payload = serviceTierWrapperCases[1].run({
       apiKey: "sk-ant-api03-test-key",

extensions/anthropic/stream-wrappers.ts

@@ -10,7 +10,6 @@ import {
   composeProviderStreamWrappers,
   createAnthropicThinkingPrefillPayloadWrapper,
   resolveAnthropicPayloadPolicy,
-  stripTrailingAnthropicAssistantPrefillWhenThinking,
   streamWithPayloadPatch,
 } from "openclaw/plugin-sdk/provider-stream-shared";
 import { createSubsystemLogger } from "openclaw/plugin-sdk/runtime-env";
@@ -44,6 +43,7 @@ const OPENCLAW_OAUTH_ANTHROPIC_BETAS = [
 ] as const;
 
 type AnthropicServiceTier = "auto" | "standard_only";
+type DynamicFastMode = boolean | (() => boolean | undefined);
 
 function isAnthropic1MModel(modelId: string): boolean {
   const normalized = normalizeLowercaseStringOrEmpty(modelId);
@@ -157,9 +157,20 @@ export function createAnthropicBetaHeadersWrapper(
 /** Wrap a stream function with the Anthropic fast-mode service tier. */
 export function createAnthropicFastModeWrapper(
   baseStreamFn: StreamFn | undefined,
-  enabled: boolean,
+  enabled: DynamicFastMode,
 ): StreamFn {
-  return createAnthropicServiceTierWrapper(baseStreamFn, resolveAnthropicFastServiceTier(enabled));
+  const underlying = baseStreamFn ?? streamSimple;
+  return (model, context, options) => {
+    const resolved = typeof enabled === "function" ? enabled() : enabled;
+    if (resolved === undefined) {
+      return underlying(model, context, options);
+    }
+    return createAnthropicServiceTierWrapper(underlying, resolveAnthropicFastServiceTier(resolved))(
+      model,
+      context,
+      options,
+    );
+  };
 }
 
 /** Wrap a stream function with an explicit Anthropic service tier when allowed. */
@@ -204,9 +215,12 @@ export function createAnthropicThinkingPrefillWrapper(
 export function resolveAnthropicFastMode(
   extraParams: Record<string, unknown> | undefined,
 ): boolean | undefined {
-  return normalizeFastMode(
-    (extraParams?.fastMode ?? extraParams?.fast_mode) as string | boolean | null | undefined,
-  );
+  const raw = extraParams?.fastMode ?? extraParams?.fast_mode;
+  const fastMode =
+    typeof raw === "function"
+      ? normalizeFastMode((raw as () => unknown)() as string | boolean | null | undefined)
+      : normalizeFastMode(raw as string | boolean | null | undefined);
+  return fastMode === "auto" ? undefined : fastMode;
 }
 
 /** Resolve Anthropic service tier from model extra params. */
@@ -232,7 +246,9 @@ export function wrapAnthropicProviderStream(
     hasConfiguredAnthropicBeta(ctx.extraParams) ||
     (ctx.extraParams?.context1m === true && isAnthropic1MModel(ctx.modelId));
   const serviceTier = resolveAnthropicServiceTier(ctx.extraParams);
-  const fastMode = resolveAnthropicFastMode(ctx.extraParams);
+  const hasFastModeParam =
+    ctx.extraParams !== undefined &&
+    (Object.hasOwn(ctx.extraParams, "fastMode") || Object.hasOwn(ctx.extraParams, "fast_mode"));
   return composeProviderStreamWrappers(
     ctx.streamFn,
     needsAnthropicBetaWrapper
@@ -241,8 +257,9 @@ export function wrapAnthropicProviderStream(
     serviceTier
       ? (streamFn) => createAnthropicServiceTierWrapper(streamFn, serviceTier)
       : undefined,
-    fastMode !== undefined
-      ? (streamFn) => createAnthropicFastModeWrapper(streamFn, fastMode)
+    hasFastModeParam
+      ? (streamFn) =>
+          createAnthropicFastModeWrapper(streamFn, () => resolveAnthropicFastMode(ctx.extraParams))
       : undefined,
     (streamFn) => createAnthropicThinkingPrefillWrapper(streamFn),
   );
@@ -251,6 +268,5 @@ export function wrapAnthropicProviderStream(
 /** Test-only hooks for Anthropic stream wrapper behavior. */
 export const testing = {
   log,
-  stripTrailingAssistantPrefillWhenThinking: stripTrailingAnthropicAssistantPrefillWhenThinking,
 };
 export { testing as __testing };

extensions/canvas/openclaw.plugin.json

@@ -6,6 +6,7 @@
   "enabledByDefault": true,
   "name": "Canvas",
   "description": "Experimental Canvas control and A2UI rendering surfaces for paired nodes.",
+  "skills": ["./skills"],
   "contracts": {
     "tools": ["canvas"]
   },

extensions/canvas/scripts/copy-a2ui.mjs

@@ -20,8 +20,27 @@ function shouldSkipMissingA2uiAssets(env = process.env) {
   return env.OPENCLAW_A2UI_SKIP_MISSING === "1" || Boolean(env.OPENCLAW_SPARSE_PROFILE);
 }
 
+function isRelativeWithin(relPath) {
+  return (
+    relPath === "" ||
+    (relPath !== ".." && !relPath.startsWith(`..${path.sep}`) && !path.isAbsolute(relPath))
+  );
+}
+
+function pathsOverlap(leftDir, rightDir) {
+  const left = path.resolve(leftDir);
+  const right = path.resolve(rightDir);
+  return (
+    isRelativeWithin(path.relative(left, right)) || isRelativeWithin(path.relative(right, left))
+  );
+}
+
 /** Copies A2UI assets, optionally tolerating missing bundles in sparse builds. */
 export async function copyA2uiAssets({ srcDir, outDir }) {
+  if (pathsOverlap(srcDir, outDir)) {
+    throw new Error("A2UI source and output directories must not overlap.");
+  }
+
   const skipMissing = shouldSkipMissingA2uiAssets(process.env);
   try {
     await fs.stat(path.join(srcDir, "index.html"));
@@ -37,6 +56,7 @@ export async function copyA2uiAssets({ srcDir, outDir }) {
     throw new Error(message, { cause: err });
   }
   await fs.mkdir(path.dirname(outDir), { recursive: true });
+  await fs.rm(outDir, { recursive: true, force: true });
   await fs.cp(srcDir, outDir, { recursive: true });
 }
 

extensions/canvas/scripts/copy-a2ui.test.ts

@@ -1,5 +1,4 @@
 // Canvas tests cover copy a2ui plugin behavior.
-import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolvePreferredOpenClawTmpDir, withTempWorkspace } from "openclaw/plugin-sdk/temp-path";
@@ -8,24 +7,6 @@ import { copyA2uiAssets } from "./copy-a2ui.mjs";
 
 const ORIGINAL_SKIP_MISSING = process.env.OPENCLAW_A2UI_SKIP_MISSING;
 const ORIGINAL_SPARSE_PROFILE = process.env.OPENCLAW_SPARSE_PROFILE;
-const REQUIRED_COMPATIBILITY_ASSETS = [
-  {
-    path: path.join("assets", "providers", "google.png"),
-    sha256: "cea7e50b816514db6ca0f21d9545173fae1669643c71ed475c45c7f8440dac53",
-  },
-  {
-    path: path.join("assets", "providers", "x.png"),
-    sha256: "307c5dbde1ad66164fcfa1d9787435d99906fa78e7ba7d068f2aa705e86ff5aa",
-  },
-  {
-    path: "granola.png",
-    sha256: "16bc6b7f1b1229c8b1984c64520c30141b62c24b156c7590f86ca50bdc494d34",
-  },
-];
-
-function sha256(bytes: Buffer): string {
-  return createHash("sha256").update(bytes).digest("hex");
-}
 
 describe("canvas a2ui copy", () => {
   beforeEach(() => {
@@ -54,24 +35,11 @@ describe("canvas a2ui copy", () => {
     );
   }
 
-  it("ships provider assets and the legacy granola compatibility image", async () => {
-    const srcDir = path.join(process.cwd(), "extensions", "canvas", "src", "host", "a2ui");
-    const pngSignature = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
-
-    for (const asset of REQUIRED_COMPATIBILITY_ASSETS) {
-      const bytes = await fs.readFile(path.join(srcDir, asset.path));
-
-      expect([...bytes.subarray(0, pngSignature.length)]).toEqual(pngSignature);
-      expect(bytes.length).toBeGreaterThan(64);
-      expect(sha256(bytes)).toBe(asset.sha256);
-    }
-  });
-
   it("throws a helpful error when assets are missing", async () => {
     await withA2uiFixture(async (dir) => {
-      await expect(copyA2uiAssets({ srcDir: dir, outDir: path.join(dir, "out") })).rejects.toThrow(
-        'Run "pnpm canvas:a2ui:bundle"',
-      );
+      await expect(
+        copyA2uiAssets({ srcDir: path.join(dir, "src"), outDir: path.join(dir, "out") }),
+      ).rejects.toThrow('Run "pnpm canvas:a2ui:bundle"');
     });
   });
 
@@ -79,7 +47,7 @@ describe("canvas a2ui copy", () => {
     await withA2uiFixture(async (dir) => {
       process.env.OPENCLAW_A2UI_SKIP_MISSING = "1";
       await expect(
-        copyA2uiAssets({ srcDir: dir, outDir: path.join(dir, "out") }),
+        copyA2uiAssets({ srcDir: path.join(dir, "src"), outDir: path.join(dir, "out") }),
       ).resolves.toBeUndefined();
     });
   });
@@ -88,7 +56,7 @@ describe("canvas a2ui copy", () => {
     await withA2uiFixture(async (dir) => {
       process.env.OPENCLAW_SPARSE_PROFILE = "core";
       await expect(
-        copyA2uiAssets({ srcDir: dir, outDir: path.join(dir, "out") }),
+        copyA2uiAssets({ srcDir: path.join(dir, "src"), outDir: path.join(dir, "out") }),
       ).resolves.toBeUndefined();
     });
   });
@@ -112,28 +80,42 @@ describe("canvas a2ui copy", () => {
     });
   });
 
-  it("preserves provider assets and the legacy granola compatibility image", async () => {
+  it("copies nested bundled assets and removes stale output", async () => {
     await withA2uiFixture(async (dir) => {
       const srcDir = path.join(dir, "src");
       const outDir = path.join(dir, "dist");
-      const providerAssetDir = path.join(srcDir, "assets", "providers");
-      await fs.mkdir(providerAssetDir, { recursive: true });
+      const nestedAssetDir = path.join(srcDir, "assets", "demo");
+      await fs.mkdir(nestedAssetDir, { recursive: true });
+      await fs.mkdir(outDir, { recursive: true });
       await fs.writeFile(path.join(srcDir, "index.html"), "<html></html>", "utf8");
       await fs.writeFile(path.join(srcDir, "a2ui.bundle.js"), "console.log(1);", "utf8");
-      await fs.writeFile(path.join(providerAssetDir, "google.png"), "google-asset", "utf8");
-      await fs.writeFile(path.join(providerAssetDir, "x.png"), "x-asset", "utf8");
-      await fs.writeFile(path.join(srcDir, "granola.png"), "legacy-granola-asset", "utf8");
+      await fs.writeFile(path.join(nestedAssetDir, "sample.txt"), "nested-asset", "utf8");
+      await fs.writeFile(path.join(outDir, "stale.txt"), "stale-output", "utf8");
 
       await copyA2uiAssets({ srcDir, outDir });
 
       await expect(
-        fs.readFile(path.join(outDir, "assets", "providers", "google.png"), "utf8"),
-      ).resolves.toBe("google-asset");
-      await expect(
-        fs.readFile(path.join(outDir, "assets", "providers", "x.png"), "utf8"),
-      ).resolves.toBe("x-asset");
-      await expect(fs.readFile(path.join(outDir, "granola.png"), "utf8")).resolves.toBe(
-        "legacy-granola-asset",
+        fs.readFile(path.join(outDir, "assets", "demo", "sample.txt"), "utf8"),
+      ).resolves.toBe("nested-asset");
+      await expect(fs.stat(path.join(outDir, "stale.txt"))).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+    });
+  });
+
+  it("rejects overlapping source and output directories before cleaning output", async () => {
+    await withA2uiFixture(async (dir) => {
+      const srcDir = path.join(dir, "src");
+      await fs.mkdir(srcDir, { recursive: true });
+      await fs.writeFile(path.join(srcDir, "index.html"), "<html></html>", "utf8");
+      await fs.writeFile(path.join(srcDir, "a2ui.bundle.js"), "console.log(1);", "utf8");
+
+      await expect(copyA2uiAssets({ srcDir, outDir: srcDir })).rejects.toThrow("must not overlap");
+      await expect(fs.readFile(path.join(srcDir, "index.html"), "utf8")).resolves.toBe(
+        "<html></html>",
+      );
+      await expect(copyA2uiAssets({ srcDir, outDir: path.join(srcDir, "dist") })).rejects.toThrow(
+        "must not overlap",
       );
     });
   });